specdacular 0.8.0 → 0.9.2

package/specdacular/workflows/context-manual-review.md

@@ -0,0 +1,410 @@
+<purpose>
+Manual review of a codebase context file (.specd/codebase/*.md). Shows a section list and lets the user pick which section to review, edit, remove, re-map, or add new content.
+
+Edits are tagged with `<!-- USER_MODIFIED: YYYY-MM-DD -->`. Re-mapping spawns a targeted agent for just that section and shows a semantic diff.
+
+Output: Updated context file with reviewed/edited sections and updated timestamps.
+</purpose>
+
+<philosophy>
+
+## User Picks What To Review
+
+Don't walk through every section automatically. Show a list of sections and let the user choose which one to look at. The user knows what needs attention.
+
+## User Controls Everything
+
+Every change requires explicit user approval. Never auto-edit, auto-remove, or auto-accept re-mapped content.
+
+## Minimal Touch
+
+Edit only what the user asks. Don't reorganize surrounding sections or rewrite adjacent content.
+
+</philosophy>
+
+<critical_rules>
+
+## Date Format
+
+Always write dates as `YYYY-MM-DD`. Never write times. Never write month names.
+
+## Section Tags
+
+Two tag types for tracking section state:
+
+- `<!-- USER_MODIFIED: YYYY-MM-DD -->` — Section was manually edited by the user
+- `<!-- AUTO_GENERATED: YYYY-MM-DD -->` — Section was generated or updated via mapper agent
+
+Sections with no tag are treated as AUTO_GENERATED with today's date. When displaying untagged sections, tell the user: "No tag found — will default to AUTO_GENERATED with today's date." Then add the tag.
+
+Placement: On its own line immediately after the section heading. No blank line between heading and tag.
+
+```markdown
+## Section Title
+<!-- USER_MODIFIED: 2026-02-17 -->
+
+Content here...
+```
+
+Never place the tag on the same line as the heading. Never add more than one tag per section. If a tag already exists, replace it with the appropriate tag type and today's date.
+
+## Section Boundaries
+
+- A `##` section runs from its heading until the next `##` heading or end of file
+- A `###` section runs from its heading until the next `###`, `##`, or end of file
+- Ignore `#` (document title) — it is not a reviewable section
+- Code fences (```) do NOT start new sections even if they contain `#` characters
+- `<!-- USER_MODIFIED: ... -->` and `<!-- AUTO_GENERATED: ... -->` tags inside fenced code blocks are NOT real tags — only detect tags outside code fences
+
+## Timestamp Lines
+
+Document-level timestamps live near the top of the file (lines 2-4), after the `# Title`:
+
+```markdown
+# Document Title
+Generated: 2026-02-04
+Last Reviewed: 2026-02-17
+Last Modified: 2026-02-17
+```
+
+If `Last Reviewed:` or `Last Modified:` lines don't exist yet, add them after the `Generated:` line (or `**Analysis Date:**` line for CONCERNS.md).
+
+## After Every Action
+
+For EVERY section acted on, you MUST add or update the tag immediately — not later, not at the end:
+
+- **User edits a section** → `<!-- USER_MODIFIED: {today} -->`
+- **Re-map accepted** → `<!-- AUTO_GENERATED: {today} -->`
+- **Section confirmed unchanged** → Update existing tag's date to today (keep same tag type). If no tag exists, add `<!-- AUTO_GENERATED: {today} -->`
+
+Also update the file's `Last Modified: {today}` timestamp at the top if any content changed (edit, remove, or re-map).
+
+When returning to the section list, update `Last Reviewed: {today}` at the top of the file.
+
+Never skip tagging. Never defer to a later step.
+
+</critical_rules>
+
+<process>
+
+<step name="validate">
+Check that codebase context files exist.
+
+```bash
+ls .specd/codebase/*.md 2>/dev/null
+```
+
+**If no files found:**
+```
+No codebase context files found.
+
+Run /specd:map-codebase to generate codebase documentation.
+```
+End workflow.
+
+Continue to select_file.
+</step>
+
+<step name="select_file">
+Let the user pick which file to review.
+
+Read the first 5 lines of each existing context file to extract timestamps. Show last reviewed dates.
+
+Use AskUserQuestion:
+- header: "Review"
+- question: "Which context file do you want to review?"
+- options (only show files that exist):
+  - "MAP.md" — Navigation map {Last Reviewed: date or "never reviewed"}
+  - "PATTERNS.md" — Code patterns {Last Reviewed: date or "never reviewed"}
+  - "STRUCTURE.md" — Directory layout {Last Reviewed: date or "never reviewed"}
+  - "CONCERNS.md" — Gotchas and warnings {Last Reviewed: date or "never reviewed"}
+
+**Set the mapper focus** based on the selected file (used by re-map action):
+- `MAP.md` → `MAPPER_FOCUS = "map"`
+- `PATTERNS.md` → `MAPPER_FOCUS = "patterns"`
+- `STRUCTURE.md` → `MAPPER_FOCUS = "structure"`
+- `CONCERNS.md` → `MAPPER_FOCUS = "concerns"`
+
+**Extract `Last Reviewed` date** from the selected file for assessment logic. Store as `LAST_REVIEWED_DATE`. If no `Last Reviewed:` line exists, set to `null`.
+
+Continue to parse_sections.
+</step>
+
+<step name="parse_sections">
+Read the selected file and build a section list.
+
+**Parse rules (from critical_rules):**
+1. Skip the `#` title line and document-level metadata (first few lines)
+2. Identify all `##` and `###` headings (outside fenced code blocks)
+3. For each heading, capture:
+   - Heading level (## or ###)
+   - Heading text
+   - Whether a tag exists on the line after the heading (USER_MODIFIED or AUTO_GENERATED)
+   - The tag type and date if present
+   - The section content (everything from after the heading/tag until the next heading of same or higher level)
+   - Parent `##` heading (for `###` sections)
+4. **Exclude empty parent sections:** If a `##` section has no content of its own (only `###` children), do NOT count it as a reviewable section. Instead, store its heading text as the parent label for its children.
+5. Count only reviewable sections (sections with actual content)
+
+Continue to show_section_list.
+</step>
+
+<step name="show_section_list">
+Show the user a numbered list of all sections with their tag status, then let them pick one or add new content.
+
+```
+================================================================
+{file} — {N} sections
+================================================================
+
+{For each section:}
+{N}. {If ### subsection: "{Parent} > "}{heading}  {If tagged: "({tag type}: {date})" else "(no tag)"}
+{...}
+
+================================================================
+```
+
+Use AskUserQuestion:
+- header: "{file}"
+- question: "How would you like to review?"
+- options:
+  - "Select section" — Pick a section by number
+  - "Walk all" — Go through every section in order
+  - "Done" — Finish reviewing this file
+
+**If "Select section":**
+Ask the user: "Which section number?" — the section list is already displayed above, so just ask for the number as a plain text prompt. Do NOT use AskUserQuestion (it has a 4-option limit and can't show all sections). Continue to show_section. After the action, return to show_section_list.
+
+**If "Walk all":**
+Continue to walk_sections.
+
+**If "Done":**
+Continue to update_timestamps.
+</step>
+
+<step name="walk_sections">
+Walk through every section in document order, one at a time.
+
+For each section in order: run the **show_section** step exactly as written below (same assessment, same display format, same AskUserQuestion options). The only addition: include "Done for now" as a 5th option. If selected, stop walking and return to show_section_list.
+
+After the user acts on a section, move to the next section automatically.
+
+After all sections are walked, return to show_section_list.
+</step>
+
+<step name="show_section">
+Display the selected section and let the user act on it.
+
+**Perform an assessment** using the assessment logic from `@~/.claude/specdacular/templates/context/section-display.md`.
+
+**Display using the section display template:**
+
+@~/.claude/specdacular/templates/context/section-display.md
+
+Follow the Section Display format from the template above exactly. Do not improvise a different format.
+
+**After displaying, use AskUserQuestion:**
+- header: "Section {N}"
+- question: "What would you like to do with this section?"
+- options:
+  - "Confirm" — Section is correct, mark as reviewed
+  - "Edit" — Tell me what to change
+  - "Remove" — Delete this section
+  - "Re-map" — Re-run the mapper for this section and compare
+
+**If Confirm:**
+Update the existing tag's date to today (keep the same tag type). If the section has no tag, add `<!-- AUTO_GENERATED: {today} -->`. Return to show_section_list.
+
+**If Edit:**
+Ask: "What should I change in this section?"
+
+Wait for user response. Apply the edit using the Edit tool.
+
+Add or update `<!-- USER_MODIFIED: {today} -->` on the line immediately after the section heading.
+
+Mark that modifications were made in this session.
+
+Return to show_section_list.
+
+**If Remove:**
+Check if this is a `##` section with `###` children.
+
+If it has children, warn:
+```
+Removing "## {title}" will also remove {N} subsections:
+- ### {child 1}
+- ### {child 2}
+...
+```
+
+Use AskUserQuestion:
+- header: "Confirm remove"
+- question: "Remove this section and its subsections?"
+- options:
+  - "Yes, remove" — Delete the section
+  - "Cancel" — Keep the section
+
+If confirmed: Remove the section (and children if ##) from the file using the Edit tool. Mark modifications made. Re-parse sections.
+
+If cancelled: Return to show_section_list.
+
+**If Re-map:**
+Spawn a targeted re-mapping agent using the `specd-codebase-mapper` agent with file-type-specific focus.
+
+Use the Task tool:
+```
+subagent_type: "specd-codebase-mapper"
+model: "sonnet"
+description: "Re-map section: {section title}"
+```
+
+**Prompt for the agent:**
+```
+Focus: {MAPPER_FOCUS}
+
+You are re-mapping a SINGLE SECTION of .specd/codebase/{file}.
+
+Section heading: {exact heading text}
+Heading level: {## or ###}
+
+Current content of this section:
+{paste the exact current section content, excluding the heading line}
+
+{If USER_MODIFIED tag exists:}
+This section was manually modified by the user on {date}.
+Preserve user additions that are still accurate.
+
+Other sections in this file (do NOT cover these topics):
+{list other section headings in the file}
+
+Explore the codebase to verify and update what this section documents.
+Check that all file paths still exist. Add new items discovered. Remove items that no longer exist.
+
+Return ONLY the replacement section content as raw markdown.
+Do NOT include the heading line.
+Do NOT write to any file.
+Do NOT wrap in code fences or add explanation.
+```
+
+**After agent returns:**
+
+Present using the Re-map Diff Display format from `@specdacular/templates/context/review-diff.md`:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RE-MAP RESULTS: {section title}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Note: AI regeneration may rephrase content even when
+facts are unchanged. Focus on factual differences.
+
+───── CURRENT ─────────────────────────────────────────
+
+{current section content}
+
+───── RE-MAPPED ───────────────────────────────────────
+
+{agent's returned content}
+
+───── KEY DIFFERENCES ─────────────────────────────────
+
+- {factual difference 1: added/removed/changed item}
+- {factual difference 2}
+...
+
+{If no factual differences: "No factual changes detected — only phrasing differences."}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use AskUserQuestion:
+- header: "Re-map"
+- question: "How do you want to handle the re-mapped content?"
+- options:
+  - "Accept new" — Replace with re-mapped content
+  - "Keep current" — Keep existing content unchanged
+  - "Edit manually" — Tell me what to change
+
+If "Accept new": Replace section content with agent's output. Add or update tag to `<!-- AUTO_GENERATED: {today} -->`. Mark modifications made.
+
+If "Keep current": Return to show_section_list.
+
+If "Edit manually": Ask user what to change. Apply edit. Add/update USER_MODIFIED tag. Mark modifications made.
+
+Return to show_section_list.
+</step>
+
+<step name="update_timestamps">
+Update the file's document-level timestamps.
+
+**Always set:**
+- `Last Reviewed: {today}` — because the user reviewed the file
+
+**If any modifications were made (edit, remove, re-map accepted, content added):**
+- `Last Modified: {today}`
+
+**How to update:**
+1. Read the first 5 lines of the file
+2. Look for existing `Last Reviewed:` and `Last Modified:` lines
+3. If they exist, update the dates using the Edit tool
+4. If they don't exist, add them after the `Generated:` or `**Analysis Date:**` line
+
+Continue to commit.
+</step>
+
+<step name="commit">
+Commit changes if any were made.
+
+**If no modifications were made (user only confirmed sections):**
+Still commit the timestamp update (Last Reviewed changed).
+
+@~/.claude/specdacular/references/commit-docs.md
+
+- **$FILES:** `.specd/codebase/{file}`
+- **$MESSAGE:** `docs: review {file}` with brief summary of changes
+- **$LABEL:** `context review`
+
+Continue to completion.
+</step>
+
+<step name="completion">
+Show review summary.
+
+```
+───────────────────────────────────────────────────────
+Review complete: {file}
+───────────────────────────────────────────────────────
+
+Sections: {total}
+- Confirmed: {N}
+- Edited: {N}
+- Removed: {N}
+- Re-mapped: {N}
+- Added: {N}
+
+Timestamps updated:
+- Last Reviewed: {today}
+{If modified:} - Last Modified: {today}
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- User selects a context file to review
+- Section list shown with tag status
+- User picks which section to review (not auto-walked)
+- Section display follows `specdacular/templates/context/section-display.md`
+- Re-map diff display follows `specdacular/templates/context/review-diff.md`
+- User can confirm, edit, remove, or re-map each section
+- Edits add USER_MODIFIED tag with date
+- Re-map accepts add AUTO_GENERATED tag with date
+- Confirms update the tag date to today (or add AUTO_GENERATED if untagged)
+- Removes warn about child sections
+- Re-map spawns `specd-codebase-mapper` agent with file-type-specific focus
+- Timestamps updated after review
+- Changes committed
+- Summary shown
+</success_criteria>

package/specdacular/workflows/continue.md

@@ -1,263 +1,26 @@
 <purpose>
-Continue a task's lifecycle. Reads state, determines the next action, and either prompts (interactive), auto-advances (semi-auto), or runs everything (auto).
+Continue a task's lifecycle. Delegates to brain.md for all flow control, state routing, mode handling, and step dispatch.
 
-This is the main driver — it dispatches to discuss, research, plan, execute, and review workflows based on current state.
-
-**Modes:**
-- **Interactive (default):** Prompts at each stage transition
-- **--semi-auto:** Auto-runs discuss→research→plan, pauses after each phase execution + review
-- **--auto:** Runs everything, only stops on review issues or task completion
+This is a thin entry point — the brain does all the work.
 </purpose>
 
 <process>
 
-<step name="parse_args">
-Parse arguments to extract task name and mode.
-
-**Parse $ARGUMENTS:**
-- Extract task name (first argument, or only argument without --)
-- Check for `--semi-auto` flag
-- Check for `--auto` flag
-- Default mode: interactive
-
-```
-Mode: {interactive | semi-auto | auto}
-Task: {task-name}
-```
-
-Continue to validate.
-</step>
-
-<step name="validate">
-@~/.claude/specdacular/references/validate-task.md
-
-Use basic validation with $TASK_NAME.
-
-Continue to load_state.
-</step>
-
-<step name="load_state">
-Read current state to determine next action.
-
-**Read:**
-- `config.json` — stage, phases info
-- `STATE.md` — progress checkboxes
-- `CONTEXT.md` — gray areas remaining
-
-**Determine current position:**
-- stage from config.json: discussion, research, planning, execution
-- phases.current_status: pending, executing, executed, completed
-- Gray areas count from CONTEXT.md
-
-Continue to determine_action.
-</step>
-
-<step name="determine_action">
-Route to the appropriate action based on state.
-
-**Routing logic:**
-
-1. **Stage = discussion, gray areas remain:**
-   → action_discuss
-
-2. **Stage = discussion, no gray areas:**
-   → action_research_or_plan
-
-3. **Stage = research (RESEARCH.md missing):**
-   → action_research
-
-4. **Stage = planning (no phases exist):**
-   → action_plan
-
-5. **Stage = planning or execution, phases.current_status = "pending":**
-   → action_execute
-
-6. **Stage = execution, phases.current_status = "executing":**
-   → action_resume_execute
-
-7. **Stage = execution, phases.current_status = "executed":**
-   → action_review
-
-8. **Stage = execution, phases.current_status = "completed":**
-   Check if more phases remain:
-   - Yes → advance to next phase, → action_execute
-   - No → action_complete
-
-Continue to the determined action step.
-</step>
-
-<step name="action_discuss">
-Offer or auto-run discussion.
-
-**Interactive mode:**
-```
-**Current state:** Discussion in progress
-**Gray areas remaining:** {count}
-
-{list gray areas}
-```
-
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Want to discuss the remaining gray areas?"
-- options:
-  - "Discuss" — Dive into gray areas (Recommended)
-  - "Skip to research" — Move on without resolving
-  - "Skip to planning" — Jump straight to planning
-
-**Semi-auto / Auto mode:**
-Auto-run discuss workflow.
-
-Dispatch to: @~/.claude/specdacular/workflows/discuss.md
-
-After completion, return to load_state (re-evaluate).
-</step>
-
-<step name="action_research_or_plan">
-Offer or auto-run research (when discussion is complete but no research yet).
-
-**Interactive mode:**
-```
-**Current state:** Discussion complete, no research yet
-```
-
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Discussion looks solid. What's next?"
-- options:
-  - "Research" — Investigate implementation patterns (Recommended)
-  - "Skip to planning" — Plan without research
-  - "Discuss more" — Continue discussion
-
-**Semi-auto / Auto mode:**
-Auto-run research workflow.
-
-Dispatch to chosen workflow. After completion, return to load_state.
-</step>
-
-<step name="action_research">
-Run research.
-
-**Interactive mode:**
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Ready to research implementation patterns?"
-- options:
-  - "Research" — Run research agents (Recommended)
-  - "Skip" — Proceed without research
-  - "Discuss first" — Go back to discussion
-
-**Semi-auto / Auto mode:**
-Auto-run research.
-
-Dispatch to: @~/.claude/specdacular/workflows/research.md
-
-After completion, return to load_state.
-</step>
-
-<step name="action_plan">
-Run planning.
-
-**Interactive mode:**
-```
-**Current state:** Ready to plan
-{If RESEARCH.md exists: "Research available — will inform planning"}
-{If no RESEARCH.md: "Note: No research. Consider running /specd:research first"}
-```
-
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Ready to create execution phases?"
-- options:
-  - "Plan" — Create phases and PLAN.md files (Recommended)
-  - "Research first" — Run research before planning
-  - "Discuss more" — Continue discussion
-
-**Semi-auto / Auto mode:**
-Auto-run planning.
-
-Dispatch to: @~/.claude/specdacular/workflows/plan.md
-
-After completion, return to load_state.
-</step>
-
-<step name="action_execute">
-Execute next phase.
-
-**Interactive mode:**
-```
-**Current state:** Phase {N} ready for execution
-**Phase:** {name} — {goal}
-**Tasks:** {count}
-```
-
-Use AskUserQuestion:
-- header: "Next Step"
-- question: "Ready to execute Phase {N}?"
-- options:
-  - "Execute" — Start phase execution (Recommended)
-  - "Review plan" — Read the PLAN.md first
-  - "Stop for now" — Come back later
-
-**Semi-auto mode:**
-Auto-execute. Review will pause for user after execution.
-
-**Auto mode:**
-Auto-execute. Review auto-approves if clean, stops only on issues.
-
-Dispatch to: @~/.claude/specdacular/workflows/execute.md
-
-Execute workflow chains to review automatically. After review completes (phase approved or stopped), return to load_state.
-</step>
-
-<step name="action_resume_execute">
-Resume interrupted execution.
-
-```
-**Resuming:** Phase {N} execution was interrupted
-**Phase:** {name}
-```
-
-Dispatch to: @~/.claude/specdacular/workflows/execute.md
-
-The execute workflow handles finding incomplete tasks within the phase.
-
-After completion, return to load_state.
-</step>
-
-<step name="action_review">
-Phase executed, needs review.
-
-**Interactive mode:**
-```
-**Current state:** Phase {N} executed, pending review
-```
-
-Dispatch to: @~/.claude/specdacular/workflows/review.md
-
-After review completes, return to load_state.
-
-**Semi-auto mode:**
-Auto-trigger review. Review will prompt user for approval.
-
-**Auto mode:**
-Auto-trigger review. If clean, auto-approve. If issues found, stop for user.
-</step>
-
-<step name="action_complete">
-All phases complete.
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- TASK COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+<step name="delegate">
+Pass all arguments through to the brain.
 
-**Task:** {task-name}
-**Phases completed:** {N}
-**Decisions made:** {N}
+The brain handles:
+- Argument parsing (task name, --interactive/--auto flags)
+- Task validation
+- Pipeline resolution (pipeline.json)
+- State-based routing
+- Mode handling (default/interactive/auto)
+- Hook execution
+- Step dispatch
+- State transitions
+- Phase loop management
 
-All phases executed and reviewed. Task is done!
-```
+@~/.claude/specdacular/workflows/brain.md
 
 End workflow.
 </step>
@@ -265,11 +28,6 @@ End workflow.
 </process>
 
 <success_criteria>
-- Correctly reads state and determines next action
-- Interactive mode prompts at each transition
-- Semi-auto mode auto-advances through discuss→research→plan, pauses after phase execution + review
-- Auto mode runs everything, stops only on review issues or completion
-- Dispatches to correct workflow at each stage
-- Loops back to state check after each workflow completes
-- Handles all edge cases (interrupted execution, missing research, etc.)
+- All arguments forwarded to brain.md
+- Brain handles all orchestration
 </success_criteria>