Initial commit

commands/amend-plan.md

@@ -0,0 +1,202 @@
+---
+description: Update existing plan and tasklist based on conversation
+---
+
+# Amend Plan Command
+
+Update an existing plan and tasklist based on conversation context. This command is used when amendments, changes, or extensions to an existing plan have been discussed. Your job is to understand those changes from the conversation and apply them safely.
+
+## Arguments
+
+**Input**: `$ARGUMENTS`
+
+**Expected format**: `/amend-plan {feature-name} [amendment description]`
+
+**Parsing:**
+
+- First token: feature name (must match existing plan)
+- Remaining tokens: optional description of changes
+  - Example: `query-command Add caching to Phase 3`
+
+**If no feature name provided:**
+
+1. List existing plans: `find plans/ -name "*-plan.md" -exec basename {} -plan.md \;`
+2. If exactly 1 plan found: use automatically and inform user
+3. If multiple plans found: use AskUserQuestion to present list and ask user to select
+4. If 0 plans found: inform user and suggest running `/write-plan` first
+
+**Feature name usage:**
+`{feature-name}` is a placeholder that gets replaced with the extracted feature name throughout this command.
+
+Example file paths:
+
+- `plans/{feature-name}-plan.md`
+- `plans/{feature-name}-tasklist.md`
+
+## Instructions
+
+### 1. Load and Analyze
+
+1. If skill `read-constitution` not loaded, load it
+2. If skill `claude-workflow` not loaded, load it
+
+Read the following if not already loaded:
+
+- `references/amendment.md`
+
+Read existing documents:
+
+- `plans/{feature-name}-plan.md`
+- `plans/{feature-name}-tasklist.md`
+
+If either missing: inform user and suggest running `/write-plan` or verifying feature name. STOP.
+
+Analyze recent conversation history (last 10-20 messages before this command) to extract:
+
+- Specific changes discussed
+- New tasks/phases to add
+- Plan sections to modify
+- Where insertions should occur
+
+Identify current state from tasklist:
+
+- Which phases complete/in-progress/not-started
+- Highest task number in each phase
+
+---
+
+### 2. Propose Amendments Interactively
+
+**STOP and present proposal** to user:
+
+```markdown
+## Proposed Amendments to {feature-name} Plan
+
+### Changes to Plan Document (plans/{feature-name}-plan.md)
+- [List sections to add/modify with brief preview]
+
+### Changes to Tasklist (plans/{feature-name}-tasklist.md)
+- [List tasks to add with IDs and descriptions]
+- [OR: New phases with goals]
+
+### Safety Check
+
+Assess amendment risk level:
+
+**Safe amendments (✅):**
+- Adding tasks to incomplete phases only
+- Creating new phases for future work
+- Adding new plan sections (no modifications)
+- No changes to completed tasks
+
+**Risky amendments (⚠️ - requires extra care):**
+- Modifying incomplete tasks in current phase
+- Changing phase structure or dependencies
+- Removing tasks or phases
+- Significant scope changes
+
+**Blocked amendments (❌ - reject and explain):**
+- Modifying or removing completed tasks
+- Modifying or removing completed phases
+- Changing task IDs of completed work
+- Retroactive changes to finished phases
+
+Assessment: [Safe/Risky/Blocked]
+Warnings: [List any concerns]
+
+Is this correct? Should I proceed?
+```
+
+Wait for confirmation. Use AskUserQuestion if needed to clarify.
+
+**Proposal Refinement:**
+
+Present the proposed amendments to the user. Then:
+
+- IF user accepts: Proceed to Section 3
+- IF user rejects: Ask what's missing/wrong/needs changing, revise the amendments, and present revised proposal (loop until accepted or aborted)
+- IF user provides feedback: Incorporate the feedback and make new proposal. Ask question if the user intent is unclear (loop until accepted or aborted)
+
+---
+
+### 3. Apply and Validate
+
+After confirmation, apply the accepted changes:
+
+1. Apply each change using the Edit tool
+2. Validate structural conformance:
+   - New sections use same markdown heading levels and structure as existing sections
+   - New tasks use `- [ ] [PX.Y] Description` format matching existing tasks
+   - Task IDs are sequential with no gaps (e.g., P3.5 → P3.6 → P3.7)
+3. If validation fails: fix and re-validate
+
+---
+
+### 4. Confirm Completion
+
+Present summary:
+
+```markdown
+## Amendments Applied ✅
+
+### Updated Files
+- plans/{feature-name}-plan.md - [changes]
+- plans/{feature-name}-tasklist.md - [changes]
+
+### Summary
+- [What was added/modified]
+- [New task IDs if applicable]
+
+### Next Steps
+- Continue amendment
+- Resume implementation
+```
+
+## Requirements
+
+- Follow safety rules from amendment.md
+- ALWAYS confirm understanding before changes
+- Make inline updates, no separate amendment sections
+
+## Example Flow
+
+```text
+Loading plan: query-command
+- Read plans/query-command-plan.md ✅
+- Read plans/query-command-tasklist.md ✅
+
+Analyzing conversation...
+You want to: add caching to Phase 3, create Phase 4 for performance testing
+
+Current state:
+- Phase 1: ✅ Complete (3/3)
+- Phase 2: ✅ Complete (4/4)
+- Phase 3: ⏳ In Progress (2/5 complete)
+
+## Proposed Amendments
+
+**Tasklist:**
+- Phase 3: Add tasks [P3.6]-[P3.8] for caching
+- Phase 4: New phase with 4 tasks for performance testing
+
+**Plan:**
+- Add "Caching Strategy" subsection to Architecture section
+
+Safety check: ✅ All amendments target incomplete phases
+
+Proceed? [User confirms]
+
+Applying...
+✅ Updated plans/query-command-plan.md (added Caching Strategy section)
+✅ Updated plans/query-command-tasklist.md (added P3.6-P3.8, new Phase 4)
+
+Validating amendments...
+✓ Plan sections match existing structure and style
+✓ Tasklist tasks match existing format
+✓ Phase 4 structure matches existing phases
+✓ Task IDs sequential (P3.6, P3.7, P3.8, P4.1, P4.2, P4.3, P4.4)
+✓ Checkboxes preserved
+✓ No completed tasks modified
+
+Done! Resume with `/implement query-command`.
+```

commands/brainstorm.md

@@ -0,0 +1,60 @@
+---
+description: Quick feature exploration before creating plan
+---
+
+# Brainstorm Command
+
+Guide conversational exploration of feature requirements and design before formalizing with /write-plan.
+
+## Context
+
+This command is run BEFORE writing planning documents to quickly explore feature requirements and design through natural conversation. The agent first understands the repository context, then asks essential questions to uncover just enough context to create comprehensive planning documents.
+
+## Arguments
+
+**Input**: `$ARGUMENTS`
+
+If arguments are provided, they contain context or initial direction for the brainstorming session. Use this context to inform your questions and exploration.
+
+## Brainstorm workflow
+
+1. If skill `read-constitution` not loaded, load it
+2. If skill `claude-workflow` not loaded, load it
+
+Read the following if not already loaded:
+
+- `references/plan-spec.md`
+
+**Gain quick repository understanding:**
+
+- Scan project structure (directories, modules, organization)
+- Identify architecture patterns (how things are currently built)
+- Note key dependencies and constraints (libraries, APIs, integrations)
+- Survey existing features (what's already implemented)
+
+Ask questions one at a time to uncover context for /write-plan. Adapt based on responses. Explore relevant code when discussing components/architecture.
+
+**Essential questions** (adapt as needed):
+
+- What does this feature do? (core functionality)
+- Why this approach? (reasoning, alternatives, apply YAGNI)
+- What components involved? (create vs modify, integration)
+- How should it be built? (strategy, phases, risks, priorities)
+- How tested? (strategy, coverage)
+- Other context? (dependencies, constraints, performance, security)
+
+**Stop when you have:**
+
+- Clear problem/solution
+- Architecture understanding
+- Key design decisions and rationale
+- Implementation strategy
+- Testing approach
+
+**Transition:** When sufficient context gathered, ask: "Ready to run /write-plan?" If yes, confirm they should run `/write-plan [feature-name]`.
+
+**Guidelines:**
+
+- 1-3 question at a time, natural conversation
+- Challenge complexity (YAGNI, DRY, orthogonality)
+- Adapt to user's preferred depth

commands/implement-plan.md

@@ -0,0 +1,209 @@
+---
+description: Execute plan phase-by-phase following tasklist
+---
+
+# Implement Command
+
+Implement a feature by following the plan and tasklist documents. This command executes an existing plan phase-by-phase, reading the plan for architectural context and the tasklist for sequential execution. Your job is to execute tasks systematically and produce working code. Work proceeds one phase at a time with human review between phases.
+
+## Arguments
+
+**Input**: `$ARGUMENTS`
+
+**Expected format**: `/implement-plan {feature-name} [implementation instructions]`
+
+**Parsing:**
+
+- First token: feature name (must match existing plan)
+- Remaining tokens: optional implementation scope or behavior
+  - Example: `query-command implement phase 1 and 2, then stop`
+
+**If no feature name provided:**
+
+1. List existing plans: `find plans/ -name "*-plan.md" -exec basename {} -plan.md \;`
+2. If exactly 1 plan found: use automatically and inform user
+3. If multiple plans found: present list (optionally with progress status), use AskUserQuestion to ask user to select
+4. If 0 plans found: inform user and suggest running `/write-plan` first
+
+**Feature name usage:**
+`{feature-name}` is a placeholder that gets replaced with the extracted feature name throughout this command.
+
+Example file paths:
+
+- `plans/{feature-name}-plan.md`
+- `plans/{feature-name}-tasklist.md`
+
+## Instructions
+
+### 1. Load Context
+
+1. If skill `read-constitution` not loaded, load it
+2. If skill `claude-workflow` not loaded, load it
+
+---
+
+### 2. Read Planning Documents
+
+Read the following if they are not already loaded:
+
+- `plans/{feature-name}-plan.md` (WHY/WHAT - architectural context)
+- `plans/{feature-name}-tasklist.md` (WHEN/HOW - sequential tasks)
+
+---
+
+### 3. Identify Next Work
+
+Find the first incomplete task in the first incomplete phase:
+
+- Scan tasklist for unchecked tasks: `- [ ] [PX.Y] Task description`
+- Identify current phase and task number
+- If all tasks complete: inform user feature is complete
+
+---
+
+### 4. Execute Tasks
+
+For each task in the current phase:
+
+1. **Read** the task description from tasklist
+2. **Implement** the task following plan guidance
+3. **Test** the task according to project standards
+4. **Mark complete** in `plans/{feature-name}-tasklist.md`:
+   - Change `- [ ] [PX.Y]` to `- [x] [PX.Y]`
+
+Repeat until all tasks in current phase are complete.
+
+---
+
+### 5. Run Phase Checkpoints
+
+After all phase tasks are marked complete:
+
+1. Execute checkpoints sequentially (defined in tasklist)
+2. Mark each checkpoint complete as it passes
+3. If checkpoint fails:
+   - Minor issues (linting, formatting, types): fix and retry until passes or stuck
+   - Major issues (architectural issues, complex problems): stop, describe to user and ask user for direction.
+   - If stuck: ask user for guidance
+4. Continue until all checkpoints pass
+
+---
+
+### 6. Complete Phase and Stop
+
+When all checkpoints pass:
+
+1. Output "Phase X Complete ✅" summary
+2. Summarize what was accomplished
+3. Suggest commit message if appropriate
+4. **STOP for human review** - do NOT proceed to next phase
+
+**Between phases:** Human reviews work, optionally runs `/clear` and if so continues with a new call to `/implement-plan {feature-name}` to resume.
+
+## Example Workflow
+
+```text
+# Starting fresh
+Reading plans for feature: query-command
+- Plan: plans/query-command-plan.md
+- Tasklist: plans/query-command-tasklist.md
+
+Progress check: No tasks completed yet. Starting from Phase 1.
+
+# Executing tasks
+Working on [P1.1]: Set up basic module structure
+[implements the task]
+✓ Marked [P1.1] as complete
+
+Working on [P1.2]: Create core data models
+[implements the task]
+✓ Marked [P1.2] as complete
+
+# Phase completion
+All Phase 1 tasks complete. Executing checkpoints...
+
+Checkpoint: Self-review implementation against phase deliverable
+✓ Marked checkpoint complete
+
+Checkpoint: Code quality - ruff check src/
+✓ Passed. Marked checkpoint complete
+
+Checkpoint: Code complexity - radon cc src/
+✓ Passed. Marked checkpoint complete
+
+Phase 1 Complete! ✅
+
+Summary of changes:
+✅ Created directory structure for modular architecture
+✅ Implemented core data models with Pydantic validation
+✅ Added type hints and proper __init__.py exports
+
+All checkpoints passed. Foundation layer complete following constitution principles.
+
+Suggested commit:
+feat: establish foundational architecture
+
+Enables modular development with core models, strict type validation,
+and clear module boundaries.
+
+
+Stopping for review. Please approve before proceeding to Phase 2.
+```
+
+If resuming mid-feature:
+
+```text
+Progress check:
+✓ Phase 1: Complete (2/2 tasks)
+✓ Phase 2: Complete (4/4 tasks)
+→ Phase 3: In progress (1/3 tasks)
+
+Resuming from Phase 3, Task [P3.2]...
+```
+
+## When Tasks Are Unclear
+
+Assess task clarity using these criteria:
+
+**Clear (✅ - proceed with implementation):**
+
+- Task goal is explicit
+- Acceptance criteria defined or obvious
+- Required files/components identified
+- Approach is straightforward or documented in plan
+
+**Minor ambiguity (⚠️ - make reasonable assumption):**
+
+- Task goal is clear but approach has 2-3 valid options
+- Some details missing but not critical to core functionality
+- Can infer intent from context and plan
+- Document assumption in code comments
+
+**Major ambiguity (❌ - stop and ask):**
+
+- Task goal is vague or has multiple interpretations
+- Missing critical information (which component, what data structure, etc.)
+- Approach unclear and not documented in plan
+- Decision affects architecture or future phases
+
+**Process:**
+
+1. Read task description carefully
+2. Check relevant plan sections for context
+3. Assess clarity level using criteria above
+4. If Major ambiguity: Use AskUserQuestion with task ID, what's unclear, which plan sections checked, and recommended approach
+5. If Minor ambiguity: Proceed with documented assumption
+6. If Clear: Proceed with implementation
+
+## When Issues Arise
+
+- Document the issue clearly
+- Use AskUserQuestion for multiple valid approaches or critical decisions
+- Continue with reasonable assumptions if minor
+- Stop and ask if significant or affects architecture
+
+## Code Quality
+
+- Keep codebase runnable throughout
+- Run tests after implementing functionality
+- Follow constitution and project principles

commands/read-constitution.md

@@ -0,0 +1,7 @@
+---
+description: Load coding principles from constitution
+---
+
+
+1. Use the Skill tool to load: `read-constitution`
+2. After loading the constitution, acknowledge that the content has been read and understood.

commands/write-plan.md

@@ -0,0 +1,157 @@
+---
+description: Create plan and tasklist from planning discussion
+---
+
+# Plan Command
+
+Formalize the planning discussion from plan mode into structured documentation. This command is run AFTER iterating with Claude in plan mode. The user has already discussed and refined the approach. Your job is to capture and formalize what was discussed.
+
+Assume the engineer using the plan has zero context for the codebase. Document everything they need: which files to touch, code/testing/docs to check, how to test. Assume they are skilled but know little about the toolset or problem domain.
+
+## Arguments
+
+**Input**: `$ARGUMENTS`
+
+**Expected format**: `/write-plan {feature-name} [planning context]`
+
+**Parsing:**
+
+- First token: feature name
+- Remaining tokens: optional planning guidance or focus areas
+  - Example: `user-auth focus on OAuth2 and session management`
+
+**Feature name requirements:**
+
+- Format: kebab-case (lowercase with hyphens)
+- Length: 1-3 words, concise and descriptive
+- Characters: lowercase letters, numbers, hyphens only
+- Examples: `query-command`, `user-auth`, `auth`, `export`
+- Avoid: special characters, uppercase, underscores
+
+**If no feature name provided:**
+
+- Analyze conversation to suggest an appropriate feature name based on discussion
+- Present suggestion: "Based on our discussion, I suggest the feature name: '{suggested-name}'"
+- Ask user to confirm before creating files
+
+**Feature name usage:**
+`{feature-name}` is a placeholder that gets replaced with the extracted feature name throughout this command.
+
+Example file paths:
+
+- `plans/{feature-name}-plan.md`
+- `plans/{feature-name}-tasklist.md`
+
+## Instructions
+
+### 1. Extract Planning Context
+
+1. If skill `read-constitution` not loaded, load it
+2. If skill `claude-workflow` not loaded, load it
+
+Read the following if not already loaded:
+
+- `references/plan-spec.md`
+- `references/tasklist-spec.md`
+
+**Context Extraction:**
+
+Analyze the conversation to extract:
+
+- Requirements and scope (IN/OUT)
+- Design decisions with rationale (WHY)
+- Alternatives considered and rejected
+- Technical constraints and dependencies
+- File and component structure
+
+Review as much of the conversation as necessary to capture all planning context. Focus particularly on recent messages and any structured outputs (e.g., /brainstorm results, design summaries, input arguments to this command).
+
+**Complexity Assessment:**
+
+Assess feature complexity (Simple/Medium/Complex) using these criteria:
+
+**Simple:**
+
+- 1-2 files affected
+- Single component or module
+- <5 tasks total
+- Minimal external dependencies
+- Focus on MUST requirements from specs
+
+**Medium:**
+
+- 3-5 files affected
+- 2-3 components involved
+- 5-15 tasks total
+- Some cross-component integration
+- Include MUST + SHOULD requirements
+
+**Complex:**
+
+- 6+ files affected
+- 4+ components involved
+- 15+ tasks total
+- Significant architectural changes or cross-system integration
+- Include MUST + SHOULD + MAY requirements
+
+---
+
+### 2. Create Planning Documents
+
+Create `plans/{feature-name}-plan.md`:
+
+- Follow plan-spec.md structure, tailoring depth to feature complexity
+- Use extracted context from Section 1
+
+Create `plans/{feature-name}-tasklist.md`:
+
+- Follow tasklist-spec.md structure, tailoring depth to feature complexity
+- Break into phases aligned with plan's Implementation Strategy
+- Include checkpoints per SKILL.md guidance
+- Stay faithful to discussion, use clear language
+
+---
+
+### 3. Validate Documents
+
+**Validate plan**:
+
+- [ ] Plan validated against all MUST/SHOULD requirements in plan-spec.md
+- [ ] If validation fails: revise plan and re-validate until all requirements pass
+
+**Validate tasklist**:
+
+- [ ] Tasklist validated against all MUST/SHOULD requirements in tasklist-spec.md
+- [ ] If validation fails: revise tasklist and re-validate until all requirements pass
+
+**Validate coherence** between documents:
+
+- [ ] Tasklist execution follows plan's Implementation Strategy pattern
+- [ ] Tasklist execution follows plan's Testing approach
+- [ ] Files marked [CREATE]/[MODIFY] in plan appear as tasks in tasklist
+- [ ] Consistent terminology between documentsss
+- [ ] Tasks reference only files/components defined in plan
+- [ ] If coherence fails: revise either document and re-validate until all checks pass
+
+---
+
+### 4. Finalization
+
+Confirm both files exist and are valid, then present summary:
+
+```text
+Planning documents created successfully! ✅
+
+Created:
+- plans/{feature-name}-plan.md
+- plans/{feature-name}-tasklist.md
+
+Implementation Structure:
+- {N} phases defined
+- {M} total tasks
+
+Next Steps:
+Run `/implement-plan {feature-name}` to begin phase-by-phase implementation.
+```
+
+Done. Wait for user to run `/implement-plan {feature-name}`.