agentleFS
PsychQuantPsychQuant/che-ical-mcp/.agents/skills/spectra-ingest/SKILL.md

spectra-ingest

Skill45 starsChanged 8 months agoMITView on GitHub

Update an existing Spectra change from external context

6 other projects use a version of this, 4 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use spectra-commit, spectra-analyze and 2 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • BananaBay69Skill

    spectra-commit

    Commit files related to a specific Spectra change

    Also in 6 projects that use this

  • harrychuangSkill

    spectra-analyze

    Analyze artifact consistency for a change

    Also in 5 projects that use this

  • harrychuangSkill

    spectra-drift

    Detect drift between a Spectra change and the current codebase state

    Also in 5 projects that use this

  • +1 more from harrychuang

The file

Show its rules and text

We split this skill into the rules it gives an agent

42 rules. 30 are common, 0 are distinctive, and 12 are very specific to this project.

  • 30

    Common

    Most of the 5 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Common:

    Update an existing Spectra change — from a plan file or conversation context.

    line 12
  2. Common:

    If the file exists → use it as the plan file source, proceed to Step 2

    line 29
  3. Common:

    If the file does NOT exist → report the error and stop

    line 30
  4. Very specific:

    Check conversation context for plan file path (plan mode system messages include the path like <name>.md)

    line 33
  5. Common:

    If found and the file exists → use the AskUserQuestion tool to ask:

    line 34
  6. Common:

    If the user picks plan file → proceed to Step 2

    line 37
  7. Common:

    If the user picks conversation context → skip Step 2, go to Step 3

    line 38
  8. Common:

    Check `` for recent files

    line 41
  9. Common:

    If recent files exist → list 5 most recent with the AskUserQuestion tool, include "Use conversation context" as an additional option

    line 42
  10. Common:

    If the user picks a file → proceed to Step 2

    line 43
  11. Common:

    Use conversation context to update artifacts

    line 47
  12. Common:

    If conversation context is insufficient, use the AskUserQuestion tool to get more details

    line 48
  13. Common:

    If one change exists (active or parked) → use the AskUserQuestion tool to confirm updating it

    line 80
  14. Common:

    If multiple changes exist → use the AskUserQuestion tool to let user pick which one to update

    line 81
  15. Very specific:

    If no changes at all (neither active nor parked) → tell the user: "No active change found.

    line 82
  16. Common:

    After selecting the change, check if it is parked:

    line 86
  17. Very specific:

    If the selected change appears in the parked array:

    line 92
  18. Common:

    Use AskUserQuestion tool to ask: continue (unpark) or cancel

    line 94
  19. Very specific:

    If continue: run spectra unpark "<name>" then proceed

    line 95
  20. Common:

    If cancel: stop the workflow

    line 96
  21. Common:

    If there is no AskUserQuestion tool available (non-Claude-Code environment): Inform the user that this change is currently parked(暫存)and …

    line 98
  22. Very specific:

    Wait for the user's response.

    line 100
  23. Common:

    Read existing artifacts for context before updating.

    line 102
  24. Very specific:

    Use the template from instructions as the output structure.

    line 112
  25. Very specific:

    Add new tasks from plan stages or conversation, preserve completed [x] items

    line 138
  26. Common:

    Do NOT remove existing content

    line 140
  27. Common:

    After creating each artifact, re-check status:

    line 144
  28. Common:

    After updating all artifacts, scan them manually.

    line 154
  29. Common:

    Do tasks cover all design decisions, and nothing outside proposal scope?

    line 169
  30. Common:

    If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed

    line 209
  31. Very specific:

    If Critical/Warning findings exist: a.

    line 210
  32. Common:

    After 2 attempts, if findings remain:

    line 215
  33. Common:

    If validation fails, fix errors and re-validate.

    line 225
  34. Common:

    Use AskUserQuestion tool to confirm the workflow is complete.

    line 235
  35. Very specific:

    If AskUserQuestion tool is not available, display the summary and inform the user to run $spectra-apply <change-name> when ready.

    line 239
  36. Common:

    NEVER: write application code — this skill only creates/updates Spectra artifacts

    line 246
  37. Very specific:

    NEVER: create new changes — ingest only updates existing changes.

    line 247
  38. Very specific:

    When updating existing changes, preserve all completed tasks ([x]) — never revert progress

    line 248
  39. Common:

    If the source content is too brief to fill all artifact sections, use the AskUserQuestion tool to get more details rather than inventing …

    line 249
  40. Very specific:

    If spectra CLI is not available, report the error and stop

    line 250
  41. Common:

    Verify each artifact file exists after writing before proceeding to next

    line 251
  42. Common:

    If AskUserQuestion tool is not available, ask the same questions as plain text and wait for the user's response

    line 253

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Update an existing Spectra change — from a plan file or conversation context.

This tool uses conversation context to update artifacts (no plan file directory). Otherwise, use conversation context to update artifacts.

Prerequisites: This skill requires the spectra CLI. If any spectra command fails with "command not found" or similar, report the error and STOP.

Input: Optionally specify a plan file path or name.

  • $spectra-ingest agile-discovering-rocket.md
  • $spectra-ingest agile-discovering-rocket
  • $spectra-ingest (use conversation context or auto-detect plan file)

Steps

  1. Locate the requirement source

    a. Argument provided → treat as plan file reference (prepend `` and append .md if needed)

    • If the file exists → use it as the plan file source, proceed to Step 2
    • If the file does NOT exist → report the error and stop

    b. No argument, plan file detectable:

    • Check conversation context for plan file path (plan mode system messages include the path like <name>.md)
    • If found and the file exists → use the AskUserQuestion tool to ask:
      • Option 1: Use the plan file
      • Option 2: Use conversation context
    • If the user picks plan file → proceed to Step 2
    • If the user picks conversation context → skip Step 2, go to Step 3

    c. No argument, no plan file detectable:

    • Check `` for recent files
    • If recent files exist → list 5 most recent with the AskUserQuestion tool, include "Use conversation context" as an additional option
    • If the user picks a file → proceed to Step 2
    • If the user picks conversation context → skip Step 2, go to Step 3

    d. Conversation context fallback (no plan files found at all):

    • Use conversation context to update artifacts
    • If conversation context is insufficient, use the AskUserQuestion tool to get more details
    • Warn: "No plan file found. Using conversation context."
  2. Parse the plan structure (skip if using conversation context)

    Claude Code plan files typically contain:

    • Title (# ...) — the high-level goal
    • Context section — background, motivation, current state
    • Stages/Steps — numbered implementation stages with goals and file lists
    • Files involved — list of files to modify/create
    • Verification section — how to test the changes

    Extract:

    • plan_title: from the H1 heading
    • plan_context: from the Context section
    • plan_stages: each numbered stage with its goal and file list
    • plan_files: all file paths mentioned
    • plan_verification: verification steps
  3. Check for active changes (REQUIRED — ingest only updates existing changes)

    spectra list --json

    Also check for parked changes:

    spectra list --parked --json

    Parse both JSON outputs to get the full list of changes (active + parked). Parked changes should be annotated with "(parked)" in any selection list.

    • If one change exists (active or parked) → use the AskUserQuestion tool to confirm updating it
    • If multiple changes exist → use the AskUserQuestion tool to let user pick which one to update
    • If no changes at all (neither active nor parked) → tell the user: "No active change found. Use $spectra-propose first to create one." and stop
  4. Select the change

    After selecting the change, check if it is parked:

    spectra list --parked --json

    If the selected change appears in the parked array:

    • Inform the user that this change is currently parked(暫存)
    • Use AskUserQuestion tool to ask: continue (unpark) or cancel
    • If continue: run spectra unpark "<name>" then proceed
    • If cancel: stop the workflow

    If there is no AskUserQuestion tool available (non-Claude-Code environment): Inform the user that this change is currently parked(暫存)and ask via plain text whether to unpark and continue, or cancel. Wait for the user's response. If the user confirms, run spectra unpark "<name>" then proceed.

    Read existing artifacts for context before updating.

  5. Update artifacts

    For each artifact, get instructions first:

    spectra instructions <artifact-id> --change "<name>" --json

    Use the template from instructions as the output structure. Apply context and rules as constraints but do NOT copy them into the file.

    The instructions JSON includes locale — the language to write artifacts in. If present, you MUST write the artifact content in that language. Exception: spec files (specs/*/*.md) MUST always be written in English regardless of locale, because they use normative language (SHALL/MUST).

    Plan-to-Artifact Mapping (when using a plan file):

    Plan SectionArtifactHow to Map
    TitleChange nameConvert to kebab-case
    Contextproposal: WhyDirect content transfer
    Stages overviewproposal: WhatSummarize all stages
    Individual stagestasks.md groupsOne stage = one ## heading, sub-items = - [ ]
    File pathsproposal: ImpactAffected code list
    Verification stepstasks.mdFinal verification task group

    Context-to-Artifact Mapping (when using conversation context):

    Conversation ElementArtifactHow to Map
    Goal / requirementproposal: WhyExtract motivation from discussion
    Discussed approachproposal: WhatSummarize agreed approach
    Mentioned filesproposal: ImpactAffected code list
    Discussion phasestasks.md groupsOne topic = one ## heading

    When updating an existing change:

    • Merge new context into existing proposal (don't replace)
    • Add new tasks from plan stages or conversation, preserve completed [x] items
    • Preserve existing [P] markers on tasks that still qualify
    • Do NOT remove existing content

    Parallel task markers ([P]): When creating or updating the tasks artifact, first read .spectra.yaml. If parallel_tasks: true is set, add [P] markers to new tasks that can be executed in parallel. Format: - [ ] [P] Task description. A task qualifies for [P] if it targets different files from other pending tasks AND has no dependency on incomplete tasks in the same group. When parallel_tasks is not enabled, do NOT add [P] markers — but still preserve any existing [P] markers already in the file.

    After creating each artifact, re-check status:

    spectra status --change "<name>" --json

    Continue until all applyRequires artifacts are complete. Show progress: "✓ Created <artifact-id>"

  6. Inline Self-Review (before CLI analysis)

    After updating all artifacts, scan them manually. Fix issues inline, then proceed to the CLI analyzer.

    Check 1: No Placeholders

    These patterns are artifact failures — fix each one before proceeding:

    • "TBD", "TODO", "FIXME", "implement later", "details to follow"
    • Vague instructions: "Add appropriate error handling", "Handle edge cases", "Write tests for the above"
    • Delegation by reference: "Similar to Task N" without repeating specifics
    • Steps describing WHAT without HOW: "Implement the authentication flow" (what flow? what steps?)
    • Empty template sections left unfilled
    • Weasel quantities: "some", "various", "several" when a specific number or list is needed

    Check 2: Internal Consistency

    • Does every capability in the proposal have a corresponding spec?
    • Does the design reference only capabilities from the proposal?
    • Do tasks cover all design decisions, and nothing outside proposal scope?
    • Are file paths consistent across proposal Impact, design, and tasks?

    Check 3: Scope Check

    • More than 15 pending tasks → consider decomposing into multiple changes
    • Any single task would take more than 1 hour → split it
    • Touches more than 3 unrelated subsystems → consider splitting

    Check 4: Ambiguity Check

    • Are success/failure conditions testable and specific?
    • Are boundary conditions defined (empty input, max limits, error cases)?
    • Could "the system" refer to multiple components? Be explicit.

    Check 5: Preservation Check (ingest-specific)

    • Are all completed tasks [x] still present and unchanged?
    • Were existing [P] markers preserved on tasks that still qualify?
    • Was existing content merged (not replaced)?

Rationalization Table

What You're ThinkingWhat You Should Do
"The existing artifacts are close enough, just adjust the tasks"Read the new context carefully. "Close enough" means you're missing something
"The proposal doesn't need updating, the change is the same"If new context exists, the proposal likely needs updates. At minimum, check
"I can merge these tasks, they're basically the same"Keep tasks granular. Merged tasks are harder to track
"The completed tasks still apply, no need to review"Verify they're still relevant to updated scope. Don't blindly keep stale work
"This spec change is minor, skip the scenario update"If the requirement changed, the scenario must change
"The conversation didn't discuss this artifact, so skip it"Absence of discussion doesn't mean absence of impact. Check

  1. Analyze-Fix Loop (max 2 iterations)

    spectra analyze <name> --json
    1. Filter findings to Critical and Warning only (ignore Suggestion)
    2. If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed
    3. If Critical/Warning findings exist: a. Show: "Found N issue(s), fixing... (attempt M/2)" b. Fix each finding in the affected artifact c. Re-run spectra analyze <name> --json d. Repeat up to 2 total iterations
    4. After 2 attempts, if findings remain:
      • Show remaining findings as a summary
      • Proceed normally (do NOT block)
  2. Validation

    spectra validate "<name>"

    If validation fails, fix errors and re-validate.

  3. Summary and next steps

    Show:

    • Source used: plan file (<path>) or conversation context
    • Change name and location
    • Artifacts created/updated
    • Validation result

    Use AskUserQuestion tool to confirm the workflow is complete. This ensures the workflow stops even when auto-accept is enabled. Provide exactly these options:

    • First option (will be auto-selected): "Done" — End the ingest workflow. Inform the user they can run $spectra-apply <change-name> when ready.
    • Second option: "Apply" — Invoke $spectra-apply <change-name> to start implementation.

    If AskUserQuestion tool is not available, display the summary and inform the user to run $spectra-apply <change-name> when ready. Then STOP — do not continue.

    After the user responds, if they chose "Done", the workflow is OVER. If they chose "Apply", invoke $spectra-apply <change-name> to begin implementation.

Guardrails

  • NEVER modify the original plan file in ``
  • NEVER write application code — this skill only creates/updates Spectra artifacts
  • NEVER create new changes — ingest only updates existing changes. If no active change exists, direct user to $spectra-propose
  • When updating existing changes, preserve all completed tasks ([x]) — never revert progress
  • If the source content is too brief to fill all artifact sections, use the AskUserQuestion tool to get more details rather than inventing content
  • If spectra CLI is not available, report the error and stop
  • Verify each artifact file exists after writing before proceeding to next
  • NEVER skip the artifact workflow to write code directly
  • If AskUserQuestion tool is not available, ask the same questions as plain text and wait for the user's response

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.