declare-cc 1.0.7 → 2.0.0

package/workflows/discuss.md

@@ -1,476 +0,0 @@
-<purpose>
-Extract implementation decisions that downstream agents need. Analyze the milestone to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied.
-
-You are a thinking partner, not an interviewer. The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
-</purpose>
-
-<downstream_awareness>
-**CONTEXT.md feeds into:**
-
-1. **declare-researcher** — Reads CONTEXT.md to know WHAT to research
-   - "User wants card-based layout" → researcher investigates card component patterns
-   - "Streaming output decided" → researcher looks into streaming API patterns
-
-2. **declare-planner** — Reads CONTEXT.md to know WHAT decisions are locked
-   - "CLI output format is JSON" → planner includes that in task specs
-   - "Claude's Discretion: error handling style" → planner can decide approach
-
-**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
-
-**Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
-</downstream_awareness>
-
-<philosophy>
-**User = founder/visionary. Claude = builder.**
-
-The user knows:
-- How they imagine it working
-- What it should look/feel like
-- What's essential vs nice-to-have
-- Specific behaviors or references they have in mind
-
-The user doesn't know (and shouldn't be asked):
-- Codebase patterns (researcher reads the code)
-- Technical risks (researcher identifies these)
-- Implementation approach (planner figures this out)
-- Success metrics (inferred from the work)
-
-Ask about vision and implementation choices. Capture decisions for downstream agents.
-</philosophy>
-
-<scope_guardrail>
-**CRITICAL: No scope creep.**
-
-The milestone boundary comes from MILESTONES.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
-
-**Allowed (clarifying ambiguity):**
-- "How should the discuss flow present gray areas?" (presentation, format, density)
-- "What happens if a milestone already has context?" (behavior choice)
-- "Interactive or auto mode?" (invocation pattern)
-
-**Not allowed (scope creep):**
-- "Should we also add a research step here?" (new capability)
-- "What about integrating with the planner directly?" (new capability)
-- "Maybe include visualization?" (new capability)
-
-**The heuristic:** Does this clarify how we implement what's already in the milestone, or does it add a new capability that could be its own milestone?
-
-**When user suggests scope creep:**
-```
-"[Feature X] would be a new capability — that's its own milestone.
-Want me to note it for the backlog?
-
-For now, let's focus on [milestone domain]."
-```
-
-Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
-</scope_guardrail>
-
-<gray_area_identification>
-Gray areas are **implementation decisions the user cares about** — things that could go multiple ways and would change the result.
-
-**How to identify gray areas:**
-
-1. **Read the milestone goal** from MILESTONES.md
-2. **Understand the domain** — What kind of thing is being built?
-   - Something users SEE → visual presentation, interactions, states matter
-   - Something users CALL → interface contracts, responses, errors matter
-   - Something users RUN → invocation, output, behavior modes matter
-   - Something users READ → structure, tone, depth, flow matter
-   - Something being ORGANIZED → criteria, grouping, handling exceptions matter
-3. **Generate milestone-specific gray areas** — Not generic categories, but concrete decisions for THIS milestone
-
-**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:
-
-```
-Milestone: "Context capture per milestone"
-→ Discussion flow, Gray area presentation, CONTEXT.md structure, Existing context handling
-
-Milestone: "Milestone research pipeline"
-→ Research depth, Source selection, Output format, Staleness policy
-
-Milestone: "CLI for database backups"
-→ Output format, Flag design, Progress reporting, Error recovery
-
-Milestone: "API documentation"
-→ Structure/navigation, Code examples depth, Versioning approach, Interactive elements
-```
-
-**The key question:** What decisions would change the outcome that the user should weigh in on?
-
-**Claude handles these (don't ask):**
-- Technical implementation details
-- Architecture patterns
-- Performance optimization
-- Scope (MILESTONES.md defines this)
-</gray_area_identification>
-
-<process>
-
-<step name="initialize" priority="first">
-Milestone ID from argument (required).
-
-```bash
-node dist/declare-tools.cjs load-graph
-```
-
-Parse the JSON. Extract milestone data for the given ID.
-
-**If graph has an `error` field:**
-```
-Project not initialized. Run /declare:init first.
-```
-Exit workflow.
-
-**If milestone ID not found in graph:**
-```
-Milestone [M-XX] not found.
-
-Use /declare:status to see available milestones.
-```
-Exit workflow.
-
-**If milestone found:** Continue to check_existing.
-</step>
-
-<step name="check_existing">
-Check if CONTEXT.md already exists in the milestone directory.
-
-```bash
-ls .planning/milestones/[M-XX]-[slug]/CONTEXT.md 2>/dev/null
-```
-
-**If exists:**
-Use AskUserQuestion:
-- header: "Context"
-- question: "Milestone [M-XX] already has context. What do you want to do?"
-- options:
-  - "Update it" — Review and revise existing context
-  - "View it" — Show me what's there
-  - "Skip" — Use existing context as-is
-
-If "Update": Load existing, continue to analyze_milestone
-If "View": Display CONTEXT.md, then offer update/skip
-If "Skip": Exit workflow
-
-**If doesn't exist:**
-
-Check if action exec plans already exist for this milestone. **If plans exist:**
-
-Use AskUserQuestion:
-- header: "Plans exist"
-- question: "Milestone [M-XX] already has action plans created without user context. Your decisions here won't affect existing plans unless you re-derive them."
-- options:
-  - "Continue anyway" — Capture context, re-derive actions afterward if needed
-  - "View existing plans" — Show plans before deciding
-  - "Cancel" — Skip discuss
-
-If "Continue anyway": Continue to analyze_milestone.
-If "View existing plans": Display plan files, then offer "Continue" / "Cancel".
-If "Cancel": Exit workflow.
-
-**If no plans exist:** Continue to analyze_milestone.
-</step>
-
-<step name="analyze_milestone">
-Analyze the milestone to identify gray areas worth discussing.
-
-**Read the milestone description from MILESTONES.md and FUTURE.md to understand context, then determine:**
-
-1. **Domain boundary** — What capability is this milestone delivering? State it clearly.
-
-2. **Gray areas** — For each relevant dimension, identify 1-2 specific ambiguities that would change implementation.
-
-3. **Skip assessment** — If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), the milestone may not need discussion.
-
-**Output your analysis internally, then present to user.**
-
-Example analysis for "Context capture per milestone":
-```
-Domain: Interactive discussion flow that captures user decisions into CONTEXT.md
-Gray areas:
-- Discussion flow: How gray areas are identified and presented
-- Existing context: What to do when CONTEXT.md already exists
-- Output structure: How decisions are organized in CONTEXT.md
-- Auto-advance: Whether to chain into planning automatically
-```
-</step>
-
-<step name="present_gray_areas">
-Present the domain boundary and gray areas to user.
-
-**First, state the boundary:**
-```
-Milestone [M-XX]: [Name]
-Domain: [What this milestone delivers — from your analysis]
-
-We'll clarify HOW to implement this.
-(New capabilities belong in other milestones.)
-```
-
-**Then use AskUserQuestion (multiSelect: true):**
-- header: "Discuss"
-- question: "Which areas do you want to discuss for [milestone name]?"
-- options: Generate 3-4 milestone-specific gray areas, each formatted as:
-  - "[Specific area]" (label) — concrete, not generic
-  - [1-2 questions this covers] (description)
-
-**Do NOT include a "skip" or "you decide" option.** User ran this command to discuss — give them real choices.
-
-**Examples by domain:**
-
-For "Context capture per milestone" (interactive flow):
-```
-Discussion flow — How many gray areas to present? In what order?
-Existing context handling — Update, view, or skip if CONTEXT.md exists?
-Output structure — How should decisions be organized in CONTEXT.md?
-Auto-advance — Chain into planning after context is captured?
-```
-
-For "Milestone research pipeline" (background process):
-```
-Research depth — Shallow scan or deep investigation per topic?
-Output format — Structured markdown, JSON, or free-form notes?
-Staleness policy — When should research be refreshed?
-Source selection — Code-only, web, or both?
-```
-
-For "CLI tooling" (command-line tool):
-```
-Output format — JSON, table, or plain text? Verbosity levels?
-Flag design — Short flags, long flags, or both? Required vs optional?
-Progress reporting — Silent, progress bar, or verbose logging?
-Error recovery — Fail fast, retry, or prompt for action?
-```
-
-Continue to discuss_areas with selected areas.
-</step>
-
-<step name="discuss_areas">
-For each selected area, conduct a focused discussion loop.
-
-**Philosophy: 4 questions, then check.**
-
-Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.
-
-**For each area:**
-
-1. **Announce the area:**
-   ```
-   Let's talk about [Area].
-   ```
-
-2. **Ask 4 questions using AskUserQuestion:**
-   - header: "[Area]" (max 12 chars — abbreviate if needed)
-   - question: Specific decision for this area
-   - options: 2-3 concrete choices (AskUserQuestion adds "Other" automatically)
-   - Include "You decide" as an option when reasonable — captures Claude discretion
-
-3. **After 4 questions, check:**
-   - header: "[Area]" (max 12 chars)
-   - question: "More questions about [area], or move to next?"
-   - options: "More questions" / "Next area"
-
-   If "More questions" → ask 4 more, then check again
-   If "Next area" → proceed to next selected area
-   If "Other" (free text) → interpret intent: continuation phrases ("chat more", "keep going", "yes", "more") map to "More questions"; advancement phrases ("done", "move on", "next", "skip") map to "Next area". If ambiguous, ask: "Continue with more questions about [area], or move to the next area?"
-
-4. **After all areas complete:**
-   - header: "Done"
-   - question: "That covers [list areas]. Ready to create context?"
-   - options: "Create context" / "Revisit an area"
-
-**Question design:**
-- Options should be concrete, not abstract ("Cards" not "Option A")
-- Each answer should inform the next question
-- If user picks "Other", receive their input, reflect it back, confirm
-
-**Scope creep handling:**
-If user mentions something outside the milestone domain:
-```
-"[Feature] sounds like a new capability — that belongs in its own milestone.
-I'll note it as a deferred idea.
-
-Back to [current area]: [return to current question]"
-```
-
-Track deferred ideas internally.
-</step>
-
-<step name="write_context">
-Create CONTEXT.md capturing decisions made.
-
-**Find or create milestone directory:**
-
-Milestone directories live at: `.planning/milestones/[M-XX]-[slug]/`
-
-If the directory doesn't exist:
-```bash
-mkdir -p ".planning/milestones/[M-XX]-[slug]"
-```
-
-**File location:** `.planning/milestones/[M-XX]-[slug]/CONTEXT.md`
-
-**Structure the content by what was discussed:**
-
-```markdown
-# Milestone [M-XX]: [Name] - Context
-
-**Gathered:** [date]
-**Status:** Ready for planning
-
-<domain>
-## Milestone Boundary
-
-[Clear statement of what this milestone delivers — the scope anchor]
-
-</domain>
-
-<decisions>
-## Implementation Decisions
-
-### [Category 1 that was discussed]
-- [Decision or preference captured]
-- [Another decision if applicable]
-
-### [Category 2 that was discussed]
-- [Decision or preference captured]
-
-### Claude's Discretion
-[Areas where user said "you decide" — note that Claude has flexibility here]
-
-</decisions>
-
-<specifics>
-## Specific Ideas
-
-[Any particular references, examples, or "I want it like X" moments from discussion]
-
-[If none: "No specific requirements — open to standard approaches"]
-
-</specifics>
-
-<deferred>
-## Deferred Ideas
-
-[Ideas that came up but belong in other milestones. Don't lose them.]
-
-[If none: "None — discussion stayed within milestone scope"]
-
-</deferred>
-
----
-
-*Milestone: [M-XX]-[slug]*
-*Context gathered: [date]*
-```
-
-Write file.
-</step>
-
-<step name="confirm_creation">
-Present summary and next steps:
-
-```
-Created: .planning/milestones/[M-XX]-[slug]/CONTEXT.md
-
-## Decisions Captured
-
-### [Category]
-- [Key decision]
-
-### [Category]
-- [Key decision]
-
-[If deferred ideas exist:]
-## Noted for Later
-- [Deferred idea] — future milestone
-
----
-
-## Next Up
-
-**Milestone [M-XX]: [Name]** — [Goal from MILESTONES.md]
-
-`/declare:execute M-XX`
-
----
-
-**Also available:**
-- Review/edit CONTEXT.md before continuing
-- `/declare:status` — see full milestone graph
-
----
-```
-</step>
-
-<step name="git_commit">
-Commit the milestone context:
-
-```bash
-node dist/declare-tools.cjs commit "docs(M-XX): capture milestone context" --files ".planning/milestones/[M-XX]-[slug]/CONTEXT.md"
-```
-
-Confirm: "Committed: docs(M-XX): capture milestone context"
-</step>
-
-<step name="auto_advance">
-Check for auto-advance trigger:
-
-1. Parse `--auto` flag from $ARGUMENTS
-2. Read `workflow.auto_advance` from config:
-   ```bash
-   node dist/declare-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false"
-   ```
-
-**If `--auto` flag present AND config not already true:** Persist to config:
-```bash
-node dist/declare-tools.cjs config-set workflow.auto_advance true
-```
-
-**If `--auto` flag present OR config is true:**
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- DECLARE ► AUTO-ADVANCING TO PLANNING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Context captured. Proceeding to milestone execution...
-```
-
-Spawn execution as Task:
-```
-Task(
-  prompt="Run /declare:execute [M-XX] --auto",
-  subagent_type="general-purpose",
-  description="Execute Milestone [M-XX]"
-)
-```
-
-**Handle execution return:**
-- **COMPLETE** → Done
-- **CHECKPOINT / needs input** → Display result, stop chain:
-  ```
-  Auto-advance stopped: Execution needs input.
-
-  Review the output above and continue manually:
-  /declare:execute [M-XX]
-  ```
-
-**If neither `--auto` nor config enabled:**
-Route to `confirm_creation` step (show manual next steps).
-</step>
-
-</process>
-
-<success_criteria>
-- Milestone validated against graph
-- Gray areas identified through intelligent analysis (not generic questions)
-- User selected which areas to discuss
-- Each selected area explored until user satisfied
-- Scope creep redirected to deferred ideas
-- CONTEXT.md captures actual decisions, not vague vision
-- Deferred ideas preserved for future milestones
-- User knows next steps
-</success_criteria>

package/workflows/future.md

@@ -1,185 +0,0 @@
-# Declaration Capture Workflow
-
-You are guiding a user through declaring their project's future. This is a conversation, not a form. Adapt your language and questions to the user's domain and energy.
-
-## Opening
-
-If there are NO existing declarations, open with:
-
-> Let's declare the future for this project.
->
-> When this project fully succeeds, what's true? Not what you want to achieve -- what IS true, as if you're looking back from that future.
->
-> I'll help you capture 3-5 declarations. Each one should be a present-tense statement of fact.
-
-If there ARE existing declarations, show them and ask:
-
-> Here are the futures you've already declared:
->
-> [list existing declarations with IDs]
->
-> Would you like to add to these, or start fresh?
-
-If `--add` mode: skip the intro entirely. Jump to the per-declaration loop with a brief:
-
-> Let's add another declaration. What's true in the future you're creating?
-
-## Per-Declaration Loop
-
-Capture 3-5 declarations (or fewer if the user is satisfied). For each:
-
-### a. Ask a guided prompt
-
-Vary the angle with each question. Do NOT repeat the same question. Draw from prompts like:
-
-- "What's true about [their domain] when this project succeeds?"
-- "If we fast-forward to the future where this is done, what do you see?"
-- "What's the reality you're creating here?"
-- "What's something that's TRUE in that future that isn't true today?"
-- "When someone uses this and it's working perfectly, what's their experience?"
-- "What does the world look like when this project has fully delivered?"
-
-Adapt the phrasing to what you know about the project. Use their language, their domain.
-
-### b. Receive and classify the user's statement
-
-After the user provides a statement, classify it using the Language Detection Guide below.
-
-### c. If past-derived or goal language: Socratic reframe
-
-Follow the reframing protocol (max 2-3 attempts, then accept). See Language Detection Guide below.
-
-### d. NSR validation
-
-After the statement passes language detection, validate against NSR criteria. See NSR Validation below.
-
-### e. Confirm and persist
-
-If the declaration passes both checks:
-- State the declaration back to the user for confirmation
-- On confirmation, call add-declaration to persist it
-- Respond: "Got it. [ID]: [declaration]. What's next?"
-
-### f. Continue or close
-
-After each declaration, gauge whether the user has more to declare. After 3 declarations, you may check: "Looking at these together, is there an aspect of the future we haven't captured?" (this also serves as the Sufficiency check).
-
----
-
-## Language Detection Guide
-
-You are the language detection engine. Use the patterns below to classify each statement.
-
-### Declared Future (ACCEPT)
-
-These are properly formed declarations. Accept them as-is.
-
-- **Present tense, stated as fact:** "Our API handles 10K RPS with <50ms p99"
-- **No causal reference to problems:** The statement stands on its own without referencing what was wrong before
-- **No aspirational language:** Not "we will" or "we aim to" -- it IS
-- **No requirement framing:** Not "the system needs to" or "it should" -- it DOES
-
-### Past-Derived Language (REFRAME)
-
-The energy comes from what's wrong, not what's possible. Reframe toward the declared future.
-
-- **References a problem:** "I want X because Y is broken/slow/bad"
-- **Reactive framing:** "We need to stop/fix/prevent X"
-- **Complaint-rooted:** The motivation is escaping something, not creating something
-- **Detection signals:** "because", "instead of", "unlike", "no more", "stop", "fix", "get rid of", "never again"
-
-### Goal Language (REFRAME)
-
-Sounds positive but is still operating from the present looking forward, not from the future looking back.
-
-- **Future aspirational:** "I want to achieve X" / "Our goal is X"
-- **Conditional:** "We should be able to X" / "We need to X"
-- **Requirement framing:** "The system must X" / "Users should be able to"
-- **Detection signals:** "want to", "goal", "aim", "achieve", "need to", "should", "will", "plan to", "hope to"
-
-### Reframing Protocol
-
-When you detect past-derived or goal language:
-
-**First attempt -- gentle, with philosophy:**
-> I hear what you're pointing at. Declarations work from the future, not against the past. What if we stated it as: "[reframe]"?
-
-or for goal language:
-> That's a great direction. Let's shift from aspiration to declaration -- as if it's already true. What about: "[reframe]"?
-
-**Second attempt -- shorter, different angle:**
-> Let me try another angle: "[different reframe]". Does that land?
-
-**Third attempt -- accept with note:**
-> I'll capture it as you've stated it. We can always refine later.
-
-Accept the user's phrasing after 2-3 reframing attempts. Never refuse a declaration outright.
-
-Show a before/after comparison ONLY when the change is significant enough to warrant it (e.g., a full sentence restructure, not a minor word swap).
-
----
-
-## NSR Validation
-
-After each declaration passes language detection, check these criteria:
-
-### Necessary
-
-Is this declaration needed? Would the future be incomplete without it?
-
-- **FAIL condition:** Overlaps significantly with an existing declaration
-- **Response:** "This seems to overlap with [other declaration]. Could we combine them, or is there a distinct aspect I'm missing?"
-
-### Sufficient (checked across the set)
-
-After 3 or more declarations have been captured, check coverage:
-
-- "Looking at these together, is there an aspect of the future we haven't captured?"
-- This is a collaborative check, not a gate. The user decides if they're done.
-
-### Relevant
-
-Is this about THIS project's future?
-
-- **FAIL condition:** Too generic ("Our code is good") or wrong scope (about a different project or the company broadly)
-- **Response:** "This feels broader than [project name]. Can we make it more specific to what this project delivers?"
-
----
-
-## Independence Check
-
-Declarations must stand alone. If a user's statement references another declaration (e.g., "Building on D-01..."), note it and suggest keeping them independent:
-
-> Declarations work best when they stand on their own -- relationships between them will emerge naturally through shared milestones during derivation. Can we restate this one independently?
-
----
-
-## Closing
-
-After the user indicates they're satisfied (or 5 declarations are captured):
-
-> Here's the future we've declared:
->
-> 1. [D-01]: [statement]
-> 2. [D-02]: [statement]
-> ...
->
-> Does this feel complete? Is there an aspect we haven't captured?
-
-If complete:
-> Your future is declared. Run `/declare:milestones` to work backward from these declarations to milestones and actions.
-
-If the user wants more: continue the loop.
-
----
-
-## Design Principles
-
-Follow these throughout the conversation:
-
-- **Feel like a dialogue, not a form.** Adapt question phrasing to the user's domain and style.
-- **The reframe should feel like a gift** ("here's a more powerful way to say that"), not a correction.
-- **Never refuse a declaration outright.** After 2-3 reframing attempts, accept.
-- **Declarations must be independent.** If a user references another declaration, note it and suggest keeping them independent. Relationships emerge via shared milestones in derivation.
-- **Gauge energy.** If the user is flowing, keep going. If they're struggling, help more actively.
-- **Do not use emojis.** Keep the tone professional and grounded.