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, 5 of them edited.
Adopted by
Most recently taken up by
- Will-SW74/passdown-osedited, first seen Oct 11, 2026
- DanSnow/hoarder-pipettetheir own version, first seen Oct 8, 2026
- leoho0722/naver-blog-image-downloaderedited, first seen Aug 31, 2026
- PsychQuant/claude-hot-limitedited, first seen Jul 1, 2026
- harrychuang/cursor-skillsedited, first seen Jun 17, 2026
- BananaBay69/claude-code-watchdogedited, first seen Apr 29, 2026
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.
BananaBay69Skillspectra-commit
Commit files related to a specific Spectra change
Also in 6 projects that use this
harrychuangSkillspectra-analyze
Analyze artifact consistency for a change
Also in 5 projects that use this
harrychuangSkillspectra-drift
Detect drift between a Spectra change and the current codebase state
Also in 5 projects that use this
- +1 more from harrychuang
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 5
- harrychuang/cursor-skills★ 1985% same
- BananaBay69/claude-code-watchdog★ 298% same
- leoho0722/naver-blog-image-downloader★ 285% same
- PsychQuant/claude-hot-limit★ 085% same
- Will-SW74/passdown-os★ 087% same
Wrote their own version · 1
- DanSnow/hoarder-pipette★ 98same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository18 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- plugin/CLAUDE.mdCLAUDE.md
- spectra-applySkill
- spectra-archiveSkill
- spectra-askSkill
- spectra-auditSkill
- spectra-debugSkill
- spectra-discussSkill
- spectra-ingestSkill
- spectra-proposeSkill
- spectra-applySkill
- spectra-archiveSkill
- spectra-askSkill
- spectra-auditSkill
- spectra-debugSkill
- spectra-discussSkill
- spectra-proposeSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
42 rules. 29 are common, 0 are distinctive, and 13 are very specific to this project.
29
Common
Most of the 6 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Common: line 13
Update an existing Spectra change — from a plan file or conversation context.
- Common: line 30
If the file exists → use it as the plan file source, proceed to Step 2
- Common: line 31
If the file does NOT exist → report the error and stop
- Very specific: line 34
Check conversation context for plan file path (plan mode system messages include the path like ~/.claude/plans/<name>.md)
- Common: line 35
If found and the file exists → use the AskUserQuestion tool to ask:
- Common: line 38
If the user picks plan file → proceed to Step 2
- Common: line 39
If the user picks conversation context → skip Step 2, go to Step 3
- Very specific: line 42
Check ~/.claude/plans/ for recent files
- Common: line 43
If recent files exist → list 5 most recent with the AskUserQuestion tool, include "Use conversation context" as an additional option
- Common: line 44
If the user picks a file → proceed to Step 2
- Common: line 48
Use conversation context to update artifacts
- Common: line 49
If conversation context is insufficient, use the AskUserQuestion tool to get more details
- Common: line 81
If one change exists (active or parked) → use the AskUserQuestion tool to confirm updating it
- Common: line 82
If multiple changes exist → use the AskUserQuestion tool to let user pick which one to update
- Very specific: line 83
If no changes at all (neither active nor parked) → tell the user: "No active change found.
- Common: line 87
After selecting the change, check if it is parked:
- Very specific: line 93
If the selected change appears in the parked array:
- Common: line 95
Use AskUserQuestion tool to ask: continue (unpark) or cancel
- Very specific: line 96
If continue: run spectra unpark "<name>" then proceed
- Common: line 97
If cancel: stop the workflow
- Common: line 99
If there is no AskUserQuestion tool available (non-Claude-Code environment): Inform the user that this change is currently parked(暫存)and …
- Very specific: line 101
Wait for the user's response.
- Common: line 103
Read existing artifacts for context before updating.
- Very specific: line 113
Use the template from instructions as the output structure.
- Very specific: line 139
Add new tasks from plan stages or conversation, preserve completed [x] items
- Common: line 141
Do NOT remove existing content
- Common: line 145
After creating each artifact, re-check status:
- Common: line 155
After updating all artifacts, scan them manually.
- Common: line 170
Do tasks cover all design decisions, and nothing outside proposal scope?
- Common: line 210
If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed
- Very specific: line 211
If Critical/Warning findings exist: a.
- Common: line 216
After 2 attempts, if findings remain:
- Common: line 226
If validation fails, fix errors and re-validate.
- Common: line 236
Use AskUserQuestion tool to confirm the workflow is complete.
- Very specific: line 240
If AskUserQuestion tool is not available, display the summary and inform the user to run /spectra-apply <change-name> when ready.
- Common: line 247
NEVER: write application code — this skill only creates/updates Spectra artifacts
- Very specific: line 248
NEVER: create new changes — ingest only updates existing changes.
- Very specific: line 249
When updating existing changes, preserve all completed tasks ([x]) — never revert progress
- Common: line 250
If the source content is too brief to fill all artifact sections, use the AskUserQuestion tool to get more details rather than inventing …
- Very specific: line 251
If spectra CLI is not available, report the error and stop
- Common: line 252
Verify each artifact file exists after writing before proceeding to next
- Common: line 254
If AskUserQuestion tool is not available, ask the same questions as plain text and wait for the user's response
“Common” is measured: kept by at least 6 in 10 of the 6 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.
Files
Update an existing Spectra change — from a plan file or conversation context.
Plan file support is available when the tool has a plan directory (~/.claude/plans/). 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 ~/.claude/plans/agile-discovering-rocket.md/spectra-ingest agile-discovering-rocket/spectra-ingest(use conversation context or auto-detect plan file)
Steps
Locate the requirement source
a. Argument provided → treat as plan file reference (prepend
~/.claude/plans/and append.mdif 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
~/.claude/plans/<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
~/.claude/plans/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."
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 headingplan_context: from the Context sectionplan_stages: each numbered stage with its goal and file listplan_files: all file paths mentionedplan_verification: verification steps
- Title (
Check for active changes (REQUIRED — ingest only updates existing changes)
spectra list --jsonAlso check for parked changes:
spectra list --parked --jsonParse 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-proposefirst to create one." and stop
Select the change
After selecting the change, check if it is parked:
spectra list --parked --jsonIf the selected change appears in the
parkedarray:- 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.
Update artifacts
For each artifact, get instructions first:
spectra instructions <artifact-id> --change "<name>" --jsonUse the
templatefrom instructions as the output structure. Applycontextandrulesas 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 Section Artifact How to Map Title Change name Convert to kebab-case Context proposal: Why Direct content transfer Stages overview proposal: What Summarize all stages Individual stages tasks.md groups One stage = one ##heading, sub-items =- [ ]File paths proposal: Impact Affected code list Verification steps tasks.md Final verification task group Context-to-Artifact Mapping (when using conversation context):
Conversation Element Artifact How to Map Goal / requirement proposal: Why Extract motivation from discussion Discussed approach proposal: What Summarize agreed approach Mentioned files proposal: Impact Affected code list Discussion phases tasks.md groups One topic = one ##headingWhen 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. Ifparallel_tasks: trueis 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. Whenparallel_tasksis 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>" --jsonContinue until all
applyRequiresartifacts are complete. Show progress: "✓ Created<artifact-id>"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 Thinking | What 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 |
Analyze-Fix Loop (max 2 iterations)
spectra analyze <name> --json- Filter findings to Critical and Warning only (ignore Suggestion)
- If no Critical/Warning findings → show "Artifacts look consistent ✓" and proceed
- 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> --jsond. Repeat up to 2 total iterations - After 2 attempts, if findings remain:
- Show remaining findings as a summary
- Proceed normally (do NOT block)
Validation
spectra validate "<name>"If validation fails, fix errors and re-validate.
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.- Source used: plan file (
Guardrails
- NEVER modify the original plan file in
~/.claude/plans/ - 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
spectraCLI 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
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
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.

