From 65bf80bf8649e957fd31672e2c1022eb3ed53ebf Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Tue, 20 Jan 2026 06:48:14 +0100 Subject: [PATCH 1/8] feat: centralize workflow files under claude_constructor/{issue_key}/ - Move all generated files to single directory per issue - Add implementation summary as final workflow step - Update create-pull-request to ignore claude_constructor folder - Update documentation to reflect new structure --- .claude-plugin/marketplace.json | 2 +- .gitignore | 3 +- CLAUDE.md | 12 +- README.md | 42 +++++-- package.json | 2 +- .../.claude-plugin/plugin.json | 2 +- .../agents/code-reviewer.md | 10 +- .../agents/increment-implementer.md | 2 +- .../agents/requirements-definer.md | 3 +- .../agents/security-reviewer.md | 8 +- .../commands/create-pull-request.md | 2 +- .../commands/create-state-management-file.md | 6 +- .../claude-constructor/commands/feature.md | 13 ++- .../commands/implement-increment.md | 4 +- .../commands/implementation-summary.md | 104 ++++++++++++++++++ 15 files changed, 174 insertions(+), 41 deletions(-) create mode 100644 plugins/claude-constructor/commands/implementation-summary.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 547a718..06c7d1c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ "name": "claude-constructor", "source": "./plugins/claude-constructor", "description": "A workflow automation system that helps Claude Code implement features systematically with built-in planning, validation, and review steps", - "version": "1.1.0" + "version": "1.2.0" } ] } diff --git a/.gitignore b/.gitignore index 3e4c6fe..9be2f8c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ .claude/settings.local.json .claude/settings.claude-constructor.local.json __pycache__ -node_modules/ \ No newline at end of file +node_modules/ +claude_constructor/ diff --git a/CLAUDE.md b/CLAUDE.md index 5a8455d..8a30fa7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,19 +37,19 @@ plugins/claude-constructor/ **State Management:** -- Workflow progress tracked in `state_management/{issue_key}.md` files (created in projects that use the plugin) +- Workflow progress tracked in `claude_constructor/{issue_key}/state_management.md` - Each workflow step updates the state file with its outputs - Enables resumable workflows and cross-step communication **Specifications:** -- Created in `specifications/{issue_key}_specification_{timestamp}.md` (in target projects) +- Created in `claude_constructor/{issue_key}/specification.md` - Contains Requirements Definition and Implementation Plan sections - Used throughout implementation and review phases **Code Reviews:** -- Review history tracked in `code_reviews/{issue_key}.md` files (created in target projects) +- Review history tracked in `claude_constructor/{issue_key}/review.md` - Each review iteration appends findings, verdict, and quality gate results - Implementation team reads latest review when addressing feedback @@ -59,9 +59,9 @@ The `/feature` command (in `commands/feature.md`) orchestrates a sequential work 1. **Planning phase**: Read config → Create state file → Read settings → Read issue → Define requirements → Validate requirements → Requirements sign-off → Write specification → Validate specification → Specification sign-off 2. **Implementation phase**: Checkout branch → Implement → Security review → Write E2E tests -3. **Review phase**: Code review → Create PR → Review PR +3. **Review phase**: Code review → Create PR → Review PR → Generate summary -Each step is a separate command. The orchestrator blocks until user sign-off at the **requirements sign-off** and **specification sign-off** steps. +Each step is a separate command. The orchestrator blocks until user sign-off at the **requirements sign-off** and **specification sign-off** steps. The workflow concludes with a comprehensive implementation summary. ### Issue Tracking Integration @@ -119,5 +119,5 @@ When modifying workflow commands or agents: 1. Use `--silent=true` argument to skip external API calls (e.g., `/feature ABC-123 --silent=true`) 2. Test with `/feature prompt-test-description` to avoid needing real issues -3. Check `state_management/`, `specifications/`, and `code_reviews/` outputs in target project +3. Check `claude_constructor/{issue_key}/` outputs (state_management.md, specification.md, review.md, security_review.md, implementation_summary.md) 4. Verify all workflow steps complete in sequence without hanging or skipping steps diff --git a/README.md b/README.md index d59b888..28d0036 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,30 @@ That's it. Claude Constructor will guide you through planning → approval → i | `/create-pull-request` | Review | | `/review-pull-request` | Review | +## Resuming Workflows + +If your session ends mid-workflow, simply run `/feature` with the same issue key. Claude Constructor will detect existing progress and offer to resume: + +```text +Progress for ABC-123: +- [x] Requirements defined + approved +- [x] Specification written + approved +- [ ] Implementation ← Resume point + +Existing workflow found for ABC-123. Resume from 'Implementation'? +> Resume (Recommended) +> Start Fresh +``` + +**What gets preserved:** + +- Approved requirements and specifications +- Completed implementation agents (parallel work) +- Security and code review history +- Git branch and PR state + +**Start Fresh:** Archives the existing state to `claude_constructor/{issue-key}-archived-{timestamp}/` and begins a new workflow. + ## Agents Specialized subagents handle complex tasks: @@ -119,16 +143,16 @@ Create `.claude/settings.claude-constructor.local.json`: Claude Constructor creates these files in your target project: ```text -state_management/ -└── {issue_key}.md # Workflow progress and context - -specifications/ -└── {issue_key}_spec_{ts}.md # Requirements + implementation plan - -code_reviews/ -└── {issue_key}.md # Review history across iterations +claude_constructor/{issue_key}/ +├── state_management.md # Workflow progress, context, and resume markers +├── specification.md # Requirements + implementation plan +├── review.md # Code review findings (all rounds) +├── security_review.md # Security review findings +└── implementation_summary.md # Final summary of what was built ``` +The `state_management.md` file tracks workflow progress including approval states, git branch, and PR URL—enabling seamless workflow resume across sessions. + ## Team Setup Add to your project's `.claude/settings.json`: @@ -178,7 +202,7 @@ Changes to command/agent files are immediately available. Changes to `plugin.jso - **Be specific:** Clear requirements upfront = better results - **Use silent mode:** `--silent=true` skips external APIs for testing -- **Check state files:** `state_management/{issue_key}.md` shows detailed progress +- **Check state files:** `claude_constructor/{issue_key}/state_management.md` shows detailed progress - **Stay engaged:** Monitor implementation and provide feedback at checkpoints ## Plugin Structure diff --git a/package.json b/package.json index 8698980..0a0d2ff 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "claude-constructor", - "version": "1.0.0", + "version": "1.2.0", "description": "A workflow automation plugin for Claude Code", "private": true, "scripts": { diff --git a/plugins/claude-constructor/.claude-plugin/plugin.json b/plugins/claude-constructor/.claude-plugin/plugin.json index c7485ba..868449f 100644 --- a/plugins/claude-constructor/.claude-plugin/plugin.json +++ b/plugins/claude-constructor/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "claude-constructor", "description": "A workflow automation system that helps Claude Code implement features systematically with built-in planning, validation, and review steps", - "version": "1.1.0", + "version": "1.2.0", "author": { "name": "Jonas Martinsson & Anders Hassis", "url": "https://github.com/Hurblat/claude-constructor/graphs/contributors" diff --git a/plugins/claude-constructor/agents/code-reviewer.md b/plugins/claude-constructor/agents/code-reviewer.md index 5cb6098..36eddde 100644 --- a/plugins/claude-constructor/agents/code-reviewer.md +++ b/plugins/claude-constructor/agents/code-reviewer.md @@ -25,7 +25,7 @@ Extract the state management file path from the prompt. 2. Extract the specification file path from the state management file 3. Read the specification to understand requirements 4. Extract the issue key from the state management file (needed for reporting and file naming) -5. Determine code-review file path: `code_reviews/{issue_key}.md` +5. Determine code-review file path: `claude_constructor/{issue_key}/review.md` 6. If code-review file exists, read it to count existing reviews (for review iteration number) ### 3. Gather Review Context @@ -118,12 +118,12 @@ Ultrathink about your findings and provide detailed feedback: ### 8. Write Review Findings to File -Write your review findings to `code_reviews/{issue_key}.md`: +Write your review findings to `claude_constructor/{issue_key}/review.md`: **If this is the first review** (file doesn't exist): -1. Create the `code_reviews/` directory if it doesn't exist -2. Create the file with header metadata: +1. Create the file with header metadata (directory should already exist from state management creation): +2. Use Write tool to create the file with header metadata: ```markdown # Code Review History @@ -209,4 +209,4 @@ or **Workflow continuation**: - If APPROVED: The orchestrator will create an issue comment with your findings and proceed to create a pull request -- If NEEDS_CHANGES: The orchestrator will loop back to the implementation step. The implementation team will read `code_reviews/{issue_key}.md` to understand what needs to be fixed +- If NEEDS_CHANGES: The orchestrator will loop back to the implementation step. The implementation team will read `claude_constructor/{issue_key}/review.md` to understand what needs to be fixed diff --git a/plugins/claude-constructor/agents/increment-implementer.md b/plugins/claude-constructor/agents/increment-implementer.md index 2684ebf..9523e9b 100644 --- a/plugins/claude-constructor/agents/increment-implementer.md +++ b/plugins/claude-constructor/agents/increment-implementer.md @@ -28,7 +28,7 @@ Extract your agent_id and state management file path from the prompt. Check if a 3. Find the Task Assignments section 4. Identify your specific tasks based on your agent_id 5. Check for code review feedback: - - Determine code-review file path: `code_reviews/{issue_key}.md` + - Determine code-review file path: `claude_constructor/{issue_key}/review.md` - If file exists: Read the latest review to understand what needs fixing - If review feedback is relevant to your tasks, prioritize addressing those issues diff --git a/plugins/claude-constructor/agents/requirements-definer.md b/plugins/claude-constructor/agents/requirements-definer.md index a4f29a1..0fb0869 100644 --- a/plugins/claude-constructor/agents/requirements-definer.md +++ b/plugins/claude-constructor/agents/requirements-definer.md @@ -39,8 +39,7 @@ When defining requirements, you will: 4. **Handle Creation vs Revision**: **Creation Mode**: - - Create a new specification file: `specifications/{issue_key}_specification_{timestamp}.md` - - Use the current timestamp to ensure uniqueness + - Create a new specification file: `claude_constructor/{issue_key}/specification.md` - Start with fresh requirements definition **Revision Mode**: diff --git a/plugins/claude-constructor/agents/security-reviewer.md b/plugins/claude-constructor/agents/security-reviewer.md index 29ce004..890baa5 100644 --- a/plugins/claude-constructor/agents/security-reviewer.md +++ b/plugins/claude-constructor/agents/security-reviewer.md @@ -21,7 +21,7 @@ When performing security review, you will: 2. **Read State Management File**: - Read the state management file provided - Extract the issue key for file naming - - Determine security review file path: `security_reviews/{issue_key}.md` + - Determine security review file path: `claude_constructor/{issue_key}/security_review.md` - If file exists, read it to count existing review iterations 3. **Execute Security Review**: @@ -29,7 +29,7 @@ When performing security review, you will: - The built-in command will analyze the codebase for security vulnerabilities 4. **Write Security Review Findings**: - - Create or append to `security_reviews/{issue_key}.md` + - Create or append to `claude_constructor/{issue_key}/security_review.md` - Include review iteration number (e.g., "Security Review #1", "Security Review #2") - Include timestamp - Write the complete output from `/security-review` @@ -85,11 +85,11 @@ or **Decision**: NEEDS_CHANGES ``` -The orchestrator will parse this decision to determine workflow routing. If APPROVED, the workflow proceeds. If NEEDS_CHANGES, the workflow loops back to implementation where agents will read the `security_reviews/{issue_key}.md` file to understand what needs to be fixed. +The orchestrator will parse this decision to determine workflow routing. If APPROVED, the workflow proceeds. If NEEDS_CHANGES, the workflow loops back to implementation where agents will read the `claude_constructor/{issue_key}/security_review.md` file to understand what needs to be fixed. ## Review Iteration Tracking -When writing to `security_reviews/{issue_key}.md`: +When writing to `claude_constructor/{issue_key}/security_review.md`: - First review: Create the file with "# Security Review #1" - Subsequent reviews: Append "# Security Review #N" sections diff --git a/plugins/claude-constructor/commands/create-pull-request.md b/plugins/claude-constructor/commands/create-pull-request.md index cf04308..1f11274 100644 --- a/plugins/claude-constructor/commands/create-pull-request.md +++ b/plugins/claude-constructor/commands/create-pull-request.md @@ -18,7 +18,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 1. List unstaged changes using `git status` -2. Read the specification linked in the state management file ($2) and compare with unstaged changes to understand how the increment has been implemented and which unstaged changes are relevant to the increment. Ignore the specifications and state_management folders. +2. Read the specification linked in the state management file ($2) and compare with unstaged changes to understand how the increment has been implemented and which unstaged changes are relevant to the increment. Ignore the claude_constructor folder. 3. Create a git commit using the guidelines in @docs/git-commit.md diff --git a/plugins/claude-constructor/commands/create-state-management-file.md b/plugins/claude-constructor/commands/create-state-management-file.md index 83a4b76..e2c5ece 100755 --- a/plugins/claude-constructor/commands/create-state-management-file.md +++ b/plugins/claude-constructor/commands/create-state-management-file.md @@ -15,7 +15,9 @@ You MUST follow all workflow steps below, not skipping any step and doing all st ## Workflow Steps -1. Create a state management file called `state_management/$1.md`. +1. Create the workflow directory for this issue using `mkdir -p claude_constructor/$1` -2. Write the following at the top of the empty state management file: +2. Create a state management file called `claude_constructor/$1/state_management.md`. + +3. Write the following content to the newly created state management file: `Issue Key: {$1}` diff --git a/plugins/claude-constructor/commands/feature.md b/plugins/claude-constructor/commands/feature.md index 80b9a53..40698c8 100644 --- a/plugins/claude-constructor/commands/feature.md +++ b/plugins/claude-constructor/commands/feature.md @@ -30,9 +30,11 @@ Create a TODO list for the workflow steps, and follow it. Before starting the workflow for user prompts, create an issue key based on $1: -- List the contents of `state_management` in the additional directories -- If there are no filenames using the format `prompt-{number}`, use issue key `prompt-1-{short-description}` -- If there is at least one filename using the format `prompt-{number}`, use issue key `prompt-{number+1}-{short-description}` +- List the contents of the `claude_constructor` directory (if it exists) +- Check for existing directories named using the pattern `prompt-{number}` (e.g., `prompt-1`, `prompt-2`) +- Determine the next issue key: + - If no `prompt-{number}` directories exist: use `prompt-1-{short-description}` + - If at least one exists: find the maximum number and use `prompt-{maxNumber+1}-{short-description}` - The short description should be a kebab-case summary of the prompt (e.g., `prompt-1-implement-cli`, `prompt-2-add-auth`) Parse optional settings arguments ($2, $3, etc.) to extract provider and silent overrides for passing to `/read-settings`. @@ -57,7 +59,7 @@ Parse optional settings arguments ($2, $3, etc.) to extract provider and silent - If APPROVED: proceed to next step - If NEEDS_CHANGES: a. Inform user that security vulnerabilities were found - b. Return to step 12 (implement increment) where agents will read security_reviews/{issue-key}.md to understand what needs to be fixed + b. Return to step 12 (implement increment) where agents will read claude_constructor/{issue-key}/security_review.md to understand what needs to be fixed c. Continue through steps 12-13 until APPROVED 14. Write end-to-end tests for the increment - use the SlashCommand tool to execute `/write-end-to-end-tests [state-management-file-path]` 15. Perform code review: @@ -74,10 +76,11 @@ Parse optional settings arguments ($2, $3, etc.) to extract provider and silent d. Proceed to next step - If NEEDS_CHANGES: a. Inform the user that code review returned NEEDS_CHANGES and implementation will be revised - b. Return to step 12 (implement increment) where implementation agents will read code_reviews/{issue-key}.md and address the issues + b. Return to step 12 (implement increment) where implementation agents will read claude_constructor/{issue-key}/review.md and address the issues c. Continue through steps 12-15 again until APPROVED 16. Create pull request - use the SlashCommand tool to execute `/create-pull-request [issue-key] [state-management-file-path]` 17. Review pull request - use the SlashCommand tool to execute `/review-pull-request [issue-key] [state-management-file-path]` +18. Generate implementation summary - use the SlashCommand tool to execute `/implementation-summary [issue-key] [state-management-file-path]` **If issue tracking system operations fail**: diff --git a/plugins/claude-constructor/commands/implement-increment.md b/plugins/claude-constructor/commands/implement-increment.md index 9258604..edbdff0 100644 --- a/plugins/claude-constructor/commands/implement-increment.md +++ b/plugins/claude-constructor/commands/implement-increment.md @@ -26,10 +26,10 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 4. Understand the division of work and implement tasks: - Read specification to identify agent_ids and Dependency Graph from the Implementation Plan - Check for code review feedback: - - Determine code-review file path: `code_reviews/{issue-key}.md` (where issue-key is $1) + - Determine code-review file path: `claude_constructor/{issue-key}/review.md` (where issue-key is $1) - If file exists: Read the latest review (most recent "Review #N" section) to understand what needs fixing - If this is a revision (code-review file exists), prioritize addressing review issues over spec additions - - Note: Subagents will automatically check for and read code_reviews/{issue-key}.md if it exists - no need to pass review content explicitly + - Note: Subagents will automatically check for and read claude_constructor/{issue-key}/review.md if it exists - no need to pass review content explicitly - Create "Implementation Agents Status" section in state management file to track progress: ```markdown diff --git a/plugins/claude-constructor/commands/implementation-summary.md b/plugins/claude-constructor/commands/implementation-summary.md new file mode 100644 index 0000000..2ad0222 --- /dev/null +++ b/plugins/claude-constructor/commands/implementation-summary.md @@ -0,0 +1,104 @@ +--- +name: implementation-summary +description: Generate final summary of implemented feature +argument-hint: [issue-key] [state-management-file-path] +model: claude-haiku-4-5 +--- + +# Implementation Summary Command + +## Purpose + +Generate a comprehensive summary of the completed feature implementation. +This command is called at the end of the workflow to provide a clear record of what was built. +You MUST follow all workflow steps below, not skipping any step and doing all steps in order. + +## Workflow Steps + +1. **Read State Management File**: + - Read the state management file ($2) + - Extract: issue key, specification file path, settings, implementation agents status + +2. **Read Specification File**: + - Read the specification file referenced in state management + - Extract: Requirements Definition summary, Implementation Plan summary + +3. **Read Review Files** (if they exist): + - Read `claude_constructor/$1/review.md` for code review history + - Read `claude_constructor/$1/security_review.md` for security review history + - Count review iterations and extract final verdicts + +4. **Gather Git Information**: + - Run `git log --oneline origin/HEAD..HEAD` to get commits made + - Run `git diff --stat origin/HEAD..HEAD` to get files changed summary + - Run `git branch --show-current` to get branch name + +5. **Get PR Information** (if not silent mode): + - Run `gh pr view --json url,number,title` to get PR details + - If command fails (no PR), note that PR was not created + +6. **Generate Summary**: + Write a summary to `claude_constructor/$1/implementation_summary.md` with the following structure: + + ```markdown + # Implementation Summary + + **Issue**: {issue_key} + **Title**: {issue_title} + **Completed**: {timestamp} + + ## What Was Requested + + {Brief summary from issue description and requirements} + + ## What Was Built + + {Summary of implementation from specification} + + ### Acceptance Criteria Status + + - [x] {criterion 1} + - [x] {criterion 2} + ... + + ## Implementation Details + + **Branch**: `{branch_name}` + **Commits**: {number of commits} + + ### Files Changed + + {git diff --stat output} + + ### Implementation Agents + + | Agent | Status | Revisions | + |-------|--------|-----------| + | {agent-id} | {status} | {count} | + + ## Quality Assurance + + ### Security Review + + - **Iterations**: {count} + - **Final Status**: {APPROVED/NEEDS_CHANGES} + + ### Code Review + + - **Iterations**: {count} + - **Final Status**: {APPROVED} + - **Quality Gates**: All passed + + ## Deliverables + + - **Pull Request**: {PR_URL or "Not created (silent mode)"} + - **Branch**: `{branch_name}` + + ## Commits + + {git log --oneline output} + ``` + +7. **Output Summary to User**: + - Display the key sections of the summary to the user + - Inform them where the full summary file is located From 57395d8f9b7db1f3b5c684af1aca77bd0becdf47 Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Tue, 20 Jan 2026 10:23:52 +0100 Subject: [PATCH 2/8] feat(workflow): add resume capability for interrupted workflows Track workflow progress markers (requirementsApproved, specificationApproved, workingBranch, pullRequestUrl) in state management file. Detect existing workflow state on /feature invocation and offer to resume from last checkpoint. Support resuming mid-implementation by skipping completed agents. Also improves implementation-summary.md with dynamic base branch detection, actual acceptance criteria status, and proper handling of missing review files. --- .../commands/create-pull-request.md | 10 +- .../commands/create-state-management-file.md | 11 +- .../claude-constructor/commands/feature.md | 110 ++++++++++++++---- .../commands/git-checkout.md | 4 + .../commands/implement-increment.md | 20 +++- .../commands/implementation-summary.md | 48 +++++--- .../commands/requirements-sign-off.md | 8 +- .../commands/specification-sign-off.md | 7 +- 8 files changed, 168 insertions(+), 50 deletions(-) diff --git a/plugins/claude-constructor/commands/create-pull-request.md b/plugins/claude-constructor/commands/create-pull-request.md index 1f11274..449bd59 100644 --- a/plugins/claude-constructor/commands/create-pull-request.md +++ b/plugins/claude-constructor/commands/create-pull-request.md @@ -33,7 +33,15 @@ You MUST follow all workflow steps below, not skipping any step and doing all st - Log: "Silent mode: Would have created PR with title 'feat: [issue key] [brief description]'" - Skip the actual PR creation -7. **Check Silent Mode for Issue Status Update**: +7. **Update Workflow Progress with PR URL**: + - If `silentMode` is `false`: + - Extract the PR URL from the `gh pr create` output (it outputs the URL on success) + - Read the state management file ($2) + - Update `pullRequestUrl:` to `pullRequestUrl: [extracted-url]` in the Workflow Progress section + - If `silentMode` is `true`: + - Update `pullRequestUrl:` to `pullRequestUrl: (silent mode - no PR created)` in the Workflow Progress section + +8. **Check Silent Mode for Issue Status Update**: - If `silentMode` is `false` AND `issueTrackingProvider` is NOT `"prompt"`: - Use the SlashCommand tool to execute `/update-issue $1 "Code Review" $2` - If `silentMode` is `true` OR `issueTrackingProvider` is `"prompt"`: diff --git a/plugins/claude-constructor/commands/create-state-management-file.md b/plugins/claude-constructor/commands/create-state-management-file.md index e2c5ece..709dc63 100755 --- a/plugins/claude-constructor/commands/create-state-management-file.md +++ b/plugins/claude-constructor/commands/create-state-management-file.md @@ -20,4 +20,13 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 2. Create a state management file called `claude_constructor/$1/state_management.md`. 3. Write the following content to the newly created state management file: -`Issue Key: {$1}` + +```markdown +Issue Key: {$1} + +## Workflow Progress +- requirementsApproved: false +- specificationApproved: false +- workingBranch: +- pullRequestUrl: +``` diff --git a/plugins/claude-constructor/commands/feature.md b/plugins/claude-constructor/commands/feature.md index 40698c8..b561758 100644 --- a/plugins/claude-constructor/commands/feature.md +++ b/plugins/claude-constructor/commands/feature.md @@ -39,30 +39,96 @@ Before starting the workflow for user prompts, create an issue key based on $1: Parse optional settings arguments ($2, $3, etc.) to extract provider and silent overrides for passing to `/read-settings`. +## Resume Detection + +Before starting the workflow, check if a previous workflow exists for this issue and offer to resume. + +### Detection Algorithm + +Check if `claude_constructor/{issue-key}/state_management.md` exists. If it does, parse the file and determine the resume point using this algorithm (check in reverse order, first match wins): + +| Check | Condition | Resume at | +|-------|-----------|-----------| +| 1 | `implementation_summary.md` exists | Complete - offer to start fresh | +| 2 | `pullRequestUrl` is set (not empty) | Step 16 (review PR) | +| 3 | `review.md` latest review has APPROVED | Step 15 (create PR) | +| 4 | `review.md` latest review has NEEDS_CHANGES | Step 11 (re-implement, code review loop) | +| 5 | `review.md` exists (any content) | Step 14 (code review - was interrupted) | +| 6 | `security_review.md` latest has APPROVED | Step 13 (write E2E tests) | +| 7 | `security_review.md` latest has NEEDS_CHANGES | Step 11 (re-implement, security loop) | +| 8 | `security_review.md` exists (any content) | Step 12 (security review - was interrupted) | +| 9 | Agent statuses all "completed" | Step 12 (security review) | +| 10 | Agent statuses exist with incomplete | Step 11 (continue implementation) | +| 11 | `workingBranch` is set, no agent statuses | Step 11 (start implementation) | +| 12 | `specificationApproved: true` | Step 10 (git checkout) | +| 13 | Implementation Plan section exists in specification | Step 9 (spec sign-off) | +| 14 | `requirementsApproved: true` | Step 7 (write spec) | +| 15 | Requirements Definition section exists in specification | Step 6 (req sign-off) | +| 16 | Settings section exists | Step 4 (define requirements) | +| 17 | State file exists only | Step 2 (read settings) | + +### Implementation Progress Display + +For implementation resume (check 10), show detailed agent progress: + +```text +Implementation progress: +- agent-1: completed +- agent-2: in_progress (revision: 1) ← will continue +- agent-3: pending ← blocked by agent-2 +``` + +### Resume UX Flow + +1. Display progress summary: + + ```text + Progress for {issue-key}: + - [x] Requirements defined + approved + - [x] Specification written + approved + - [ ] Implementation ← Resume point + ``` + +2. Use AskUserQuestion tool: + - question: "Existing workflow found for {issue-key}. Resume from '{step-name}'?" + - header: "Resume" + - options: + - label: "Resume (Recommended)" + description: "Continue from {step-name}, preserving existing progress" + - label: "Start Fresh" + description: "Archive existing state and begin new workflow" + +3. If user chooses "Start Fresh": + - Rename `claude_constructor/{issue-key}/` → `claude_constructor/{issue-key}-archived-{timestamp}/` + - Create fresh state file and start from step 1 + +4. If user chooses "Resume": + - Skip to the detected resume step + - For step 11 resume, `/implement-increment` will handle skipping completed agents + ## Workflow Steps -1. Read @CLAUDE.md: General principles, quality gates, and development workflow. If the @CLAUDE.md refers to other @CLAUDE.md files, read those as well. -2. Create a state management file for this increment - use the SlashCommand tool to execute `/create-state-management-file $1` if the workflow was started from an issue, or the issue key if it was started from a prompt -3. Read settings - use the SlashCommand tool to execute `/read-settings [state-management-file-path]` with any optional settings arguments from $2+ (e.g., `/read-settings [path] --provider=prompt --silent=true`) -4. Read issue - check the issueTrackingProvider in the Settings section of the state management file. If not "prompt", use the SlashCommand tool to execute `/read-issue [issue-key] [state-management-file-path]`. If "prompt", skip this step as there is no external issue to read. -5. Define requirements - Use the requirements-definer subagent to define requirements for [state-management-file-path] -6. Audit requirements - Use the requirements-definer-auditor subagent to audit requirements in [state-management-file-path]. If audit fails with critical issues, return to step 5 to address them. -7. Get sign-off on requirements. You are not allowed to go to step 8 until the user has signed off on the requirements. Use the SlashCommand tool to execute `/requirements-sign-off [state-management-file-path]` -8. Write specification - Use the specification-writer subagent to write specification for [state-management-file-path] -9. Audit specification - Use the specification-writer-auditor subagent to audit specification in [state-management-file-path]. If audit fails with critical issues, return to step 8 to address them. -10. Get sign-off on specification. You are not allowed to go to step 11 until the user has signed off on the specification. Use the SlashCommand tool to execute `/specification-sign-off [state-management-file-path]` -11. Check out new branch - use the SlashCommand tool to execute `/git-checkout [issue-key] [state-management-file-path]` -12. Implement increment - use the SlashCommand tool to execute `/implement-increment [issue-key] [state-management-file-path]` -13. Perform security review: +1. Create a state management file for this increment - use the SlashCommand tool to execute `/create-state-management-file $1` if the workflow was started from an issue, or the issue key if it was started from a prompt +2. Read settings - use the SlashCommand tool to execute `/read-settings [state-management-file-path]` with any optional settings arguments from $2+ (e.g., `/read-settings [path] --provider=prompt --silent=true`) +3. Read issue - check the issueTrackingProvider in the Settings section of the state management file. If not "prompt", use the SlashCommand tool to execute `/read-issue [issue-key] [state-management-file-path]`. If "prompt", skip this step as there is no external issue to read. +4. Define requirements - Use the requirements-definer subagent to define requirements for [state-management-file-path] +5. Audit requirements - Use the requirements-definer-auditor subagent to audit requirements in [state-management-file-path]. If audit fails with critical issues, return to step 4 to address them. +6. Get sign-off on requirements. You are not allowed to go to step 7 until the user has signed off on the requirements. Use the SlashCommand tool to execute `/requirements-sign-off [state-management-file-path]` +7. Write specification - Use the specification-writer subagent to write specification for [state-management-file-path] +8. Audit specification - Use the specification-writer-auditor subagent to audit specification in [state-management-file-path]. If audit fails with critical issues, return to step 7 to address them. +9. Get sign-off on specification. You are not allowed to go to step 10 until the user has signed off on the specification. Use the SlashCommand tool to execute `/specification-sign-off [state-management-file-path]` +10. Check out new branch - use the SlashCommand tool to execute `/git-checkout [issue-key] [state-management-file-path]` +11. Implement increment - use the SlashCommand tool to execute `/implement-increment [issue-key] [state-management-file-path]` +12. Perform security review: - Use the security-reviewer subagent to analyze the implementation at [state-management-file-path] - Parse the verdict from the subagent's output (look for "**Decision**: APPROVED" or "**Decision**: NEEDS_CHANGES") - If APPROVED: proceed to next step - If NEEDS_CHANGES: a. Inform user that security vulnerabilities were found - b. Return to step 12 (implement increment) where agents will read claude_constructor/{issue-key}/security_review.md to understand what needs to be fixed - c. Continue through steps 12-13 until APPROVED -14. Write end-to-end tests for the increment - use the SlashCommand tool to execute `/write-end-to-end-tests [state-management-file-path]` -15. Perform code review: + b. Return to step 11 (implement increment) where agents will read claude_constructor/{issue-key}/security_review.md to understand what needs to be fixed + c. Continue through steps 11-12 until APPROVED +13. Write end-to-end tests for the increment - use the SlashCommand tool to execute `/write-end-to-end-tests [state-management-file-path]` +14. Perform code review: - Use the code-reviewer subagent to review the implementation for [state-management-file-path] - Parse the verdict from the agent's output (look for "**Decision**: APPROVED" or "**Decision**: NEEDS_CHANGES") - If APPROVED: @@ -76,11 +142,11 @@ Parse optional settings arguments ($2, $3, etc.) to extract provider and silent d. Proceed to next step - If NEEDS_CHANGES: a. Inform the user that code review returned NEEDS_CHANGES and implementation will be revised - b. Return to step 12 (implement increment) where implementation agents will read claude_constructor/{issue-key}/review.md and address the issues - c. Continue through steps 12-15 again until APPROVED -16. Create pull request - use the SlashCommand tool to execute `/create-pull-request [issue-key] [state-management-file-path]` -17. Review pull request - use the SlashCommand tool to execute `/review-pull-request [issue-key] [state-management-file-path]` -18. Generate implementation summary - use the SlashCommand tool to execute `/implementation-summary [issue-key] [state-management-file-path]` + b. Return to step 11 (implement increment) where implementation agents will read claude_constructor/{issue-key}/review.md and address the issues + c. Continue through steps 11-14 again until APPROVED +15. Create pull request - use the SlashCommand tool to execute `/create-pull-request [issue-key] [state-management-file-path]` +16. Review pull request - use the SlashCommand tool to execute `/review-pull-request [issue-key] [state-management-file-path]` +17. Generate implementation summary - use the SlashCommand tool to execute `/implementation-summary [issue-key] [state-management-file-path]` **If issue tracking system operations fail**: diff --git a/plugins/claude-constructor/commands/git-checkout.md b/plugins/claude-constructor/commands/git-checkout.md index 8a9b77d..1d99c17 100644 --- a/plugins/claude-constructor/commands/git-checkout.md +++ b/plugins/claude-constructor/commands/git-checkout.md @@ -22,3 +22,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 3. Ensure that you have the latest changes, using `git pull` 4. Check out a new branch, using `git checkout -b feat/$1` + +5. **Update Workflow Progress**: + - Read the state management file ($2) + - Update `workingBranch:` to `workingBranch: feat/$1` in the Workflow Progress section diff --git a/plugins/claude-constructor/commands/implement-increment.md b/plugins/claude-constructor/commands/implement-increment.md index edbdff0..3fe2664 100644 --- a/plugins/claude-constructor/commands/implement-increment.md +++ b/plugins/claude-constructor/commands/implement-increment.md @@ -30,13 +30,21 @@ You MUST follow all workflow steps below, not skipping any step and doing all st - If file exists: Read the latest review (most recent "Review #N" section) to understand what needs fixing - If this is a revision (code-review file exists), prioritize addressing review issues over spec additions - Note: Subagents will automatically check for and read claude_constructor/{issue-key}/review.md if it exists - no need to pass review content explicitly - - Create "Implementation Agents Status" section in state management file to track progress: + - **Check for existing Implementation Agents Status** (resume support): + - Read the state management file ($2) + - If `## Implementation Agents Status` section already exists: + - Parse existing agent statuses and revision counts + - Skip agents marked as "completed" - their work is preserved + - Resume agents marked as "in_progress" or "needs_revision" + - Preserve existing revision counts when resuming + - Log: "Resuming implementation - skipping N completed agents" + - If section does not exist, create it fresh: - ```markdown - ## Implementation Agents Status - - agent-1: pending (revision: 0) - - agent-2: pending (revision: 0) - ``` + ```markdown + ## Implementation Agents Status + - agent-1: pending (revision: 0) + - agent-2: pending (revision: 0) + ``` - Process agents in dependency order: a. Identify agents with no dependencies or whose dependencies are complete diff --git a/plugins/claude-constructor/commands/implementation-summary.md b/plugins/claude-constructor/commands/implementation-summary.md index 2ad0222..aeb4db7 100644 --- a/plugins/claude-constructor/commands/implementation-summary.md +++ b/plugins/claude-constructor/commands/implementation-summary.md @@ -23,19 +23,26 @@ You MUST follow all workflow steps below, not skipping any step and doing all st - Read the specification file referenced in state management - Extract: Requirements Definition summary, Implementation Plan summary -3. **Read Review Files** (if they exist): - - Read `claude_constructor/$1/review.md` for code review history - - Read `claude_constructor/$1/security_review.md` for security review history - - Count review iterations and extract final verdicts - -4. **Gather Git Information**: - - Run `git log --oneline origin/HEAD..HEAD` to get commits made - - Run `git diff --stat origin/HEAD..HEAD` to get files changed summary - - Run `git branch --show-current` to get branch name - -5. **Get PR Information** (if not silent mode): - - Run `gh pr view --json url,number,title` to get PR details - - If command fails (no PR), note that PR was not created +3. **Read Review Files**: + - Check if `claude_constructor/$1/review.md` exists: + - If exists: Read for code review history, count review iterations, extract final verdict + - If missing: Set code review iterations to 0, final verdict to "N/A", include "No code review performed" in summary + - Check if `claude_constructor/$1/security_review.md` exists: + - If exists: Read for security review history, count iterations, extract final verdict + - If missing: Set security review iterations to 0, final verdict to "N/A", include "No security review performed" in summary + +4. **Get PR Information** (if not silent mode): + - Run `gh pr view --json url,number,title,baseRefName` to get PR details including base branch + - Extract `baseRefName` from the response (e.g., "main", "develop") + - If command fails (no PR), note that PR was not created and set `baseRefName` to null + +5. **Gather Git Information**: + - Run `git branch --show-current` to get current branch name + - Determine comparison base: + - If `baseRefName` was extracted from PR: use `origin/{baseRefName}` as the base + - If no PR context (silent mode or no PR): fall back to `origin/HEAD` and note in summary that commit/diff info may be incomplete + - Run `git log --oneline {base}..HEAD` to get commits made (where `{base}` is the determined comparison base) + - Run `git diff --stat {base}..HEAD` to get files changed summary 6. **Generate Summary**: Write a summary to `claude_constructor/$1/implementation_summary.md` with the following structure: @@ -57,8 +64,14 @@ You MUST follow all workflow steps below, not skipping any step and doing all st ### Acceptance Criteria Status - - [x] {criterion 1} - - [x] {criterion 2} + For each acceptance criterion from the Requirements Definition section: + - Read the specification and implementation to determine if criterion was met + - Mark with `[x]` if criterion is verifiably completed (code exists, tests pass) + - Mark with `[ ]` if criterion was not implemented or cannot be verified + - Mark with `[~]` if partially implemented + + - [{status}] {criterion 1} + - [{status}] {criterion 2} ... ## Implementation Details @@ -81,13 +94,12 @@ You MUST follow all workflow steps below, not skipping any step and doing all st ### Security Review - **Iterations**: {count} - - **Final Status**: {APPROVED/NEEDS_CHANGES} + - **Final Status**: {APPROVED/NEEDS_CHANGES/N/A} ### Code Review - **Iterations**: {count} - - **Final Status**: {APPROVED} - - **Quality Gates**: All passed + - **Final Status**: {APPROVED/N/A} ## Deliverables diff --git a/plugins/claude-constructor/commands/requirements-sign-off.md b/plugins/claude-constructor/commands/requirements-sign-off.md index 4f1bfcd..0b3560c 100644 --- a/plugins/claude-constructor/commands/requirements-sign-off.md +++ b/plugins/claude-constructor/commands/requirements-sign-off.md @@ -19,6 +19,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st - Read the state management file (path in $1) - Locate the specification file path - Present the Requirements Definition section to the user for review + - Tell the user where to find the full specification: "You can review the full specification at: `{specification-file-path}`" 2. **Get User Feedback**: - Ask the user to read and provide feedback on the Requirements Definition @@ -32,4 +33,9 @@ You MUST follow all workflow steps below, not skipping any step and doing all st b. The subagent will detect the feedback and revise accordingly c. Return to step 1 for re-review - - If user provides explicit sign-off, requirements sign-off is complete + - If user provides explicit sign-off, proceed to step 3 + +3. **Update Workflow Progress**: + - Read the state management file ($1) + - Update `requirementsApproved: false` to `requirementsApproved: true` in the Workflow Progress section + - Requirements sign-off is complete diff --git a/plugins/claude-constructor/commands/specification-sign-off.md b/plugins/claude-constructor/commands/specification-sign-off.md index 92d3f51..502ec84 100644 --- a/plugins/claude-constructor/commands/specification-sign-off.md +++ b/plugins/claude-constructor/commands/specification-sign-off.md @@ -19,6 +19,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st - Read the state management file (path in $1) - Locate the specification file path - Present the Implementation Plan section to the user for review + - Tell the user where to find the full specification: "You can review the full specification at: `{specification-file-path}`" 2. **Get User Feedback**: - Ask the user to read and provide feedback on the Implementation Plan @@ -34,7 +35,11 @@ You MUST follow all workflow steps below, not skipping any step and doing all st c. Return to step 1 for re-review - If user provides explicit sign-off, proceed to step 3 -3. **Add Issue Comment**: +3. **Update Workflow Progress**: + - Read the state management file ($1) + - Update `specificationApproved: false` to `specificationApproved: true` in the Workflow Progress section + +4. **Add Issue Comment**: - Did you get explicit approval on the specification? If not, go back to step 2. - Read the state management file to get the issue key - Use the SlashCommand tool to execute `/create-comment [issue-key] "[specification details and assumptions]"` From 8bcfa5b1157304f87218d159b523c3577e6dfc9a Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Tue, 20 Jan 2026 10:34:13 +0100 Subject: [PATCH 3/8] feat(workflow): add interactive question resolution via AskUserQuestion Transform passive Open Questions sections into interactive resolution during sign-off. Questions tagged as [STRUCTURED] get resolved via multiple-choice UI, while [OPEN-ENDED] questions remain for manual feedback. - Add question classification format to requirements-definer and specification-writer - Add interactive resolution workflow to sign-off commands - Add question format validation to auditors Co-Authored-By: Claude Opus 4.5 --- .../agents/requirements-definer-auditor.md | 8 +++++ .../agents/requirements-definer.md | 31 ++++++++++++++++- .../agents/specification-writer-auditor.md | 8 +++++ .../agents/specification-writer.md | 34 ++++++++++++++++++- .../commands/requirements-sign-off.md | 30 ++++++++++++++-- .../commands/specification-sign-off.md | 32 ++++++++++++++--- 6 files changed, 134 insertions(+), 9 deletions(-) diff --git a/plugins/claude-constructor/agents/requirements-definer-auditor.md b/plugins/claude-constructor/agents/requirements-definer-auditor.md index b1d519d..eb55394 100644 --- a/plugins/claude-constructor/agents/requirements-definer-auditor.md +++ b/plugins/claude-constructor/agents/requirements-definer-auditor.md @@ -85,6 +85,14 @@ When auditing requirements, you will: - Validate integration point clarity - Assess technical constraint documentation +#### 7. Open Questions Format Audit + +- Verify all questions are tagged as `[STRUCTURED]` or `[OPEN-ENDED]` +- Check STRUCTURED questions have exactly 2-4 options +- Validate options are mutually exclusive and clearly distinct +- Ensure questions are specific and answerable +- Verify option descriptions provide enough context for decision-making + 5. **Detect Zero-Tolerance Issues**: Identify automatic fail conditions: - Missing critical sections (Business Value, Acceptance Criteria) diff --git a/plugins/claude-constructor/agents/requirements-definer.md b/plugins/claude-constructor/agents/requirements-definer.md index 0fb0869..caa83e8 100644 --- a/plugins/claude-constructor/agents/requirements-definer.md +++ b/plugins/claude-constructor/agents/requirements-definer.md @@ -92,7 +92,36 @@ When defining requirements, you will: - **Integration Points**: How this integrates with existing systems or components - **Error Handling**: How errors and edge cases should be handled gracefully - **Performance Expectations**: Any specific performance or scalability requirements - - **Open Questions**: Anything that needs clarification from the user or stakeholders + - **Open Questions**: Questions that need clarification from the user or stakeholders + + For each question, classify and format: + + **STRUCTURED questions** (answerable with 2-4 discrete options): + + ```markdown + #### [STRUCTURED] Question title + + Full question text? + + - **Option A**: First option description + - **Option B**: Second option description + - **Option C**: Third option (if needed) + - **Option D**: Fourth option (if needed) + ``` + + **OPEN-ENDED questions** (require detailed explanation): + + ```markdown + #### [OPEN-ENDED] Question title + + Full question text requiring free-form response? + ``` + + Guidelines: + + - Prefer STRUCTURED when possible (faster resolution) + - STRUCTURED questions must have exactly 2-4 options + - Options should be mutually exclusive 8. **Focus on "What" not "How"**: - Define what needs to be accomplished, not how to implement it diff --git a/plugins/claude-constructor/agents/specification-writer-auditor.md b/plugins/claude-constructor/agents/specification-writer-auditor.md index d72a95a..a57b015 100644 --- a/plugins/claude-constructor/agents/specification-writer-auditor.md +++ b/plugins/claude-constructor/agents/specification-writer-auditor.md @@ -90,6 +90,14 @@ When auditing specifications, you will: - Confirm implementation stays within requirement boundaries - Identify potential scope expansion risks +#### 7. Technical Questions Format Audit + +- Verify all questions are tagged as `[STRUCTURED]` or `[OPEN-ENDED]` +- Check STRUCTURED questions have exactly 2-4 options +- Validate options represent valid technical alternatives +- Ensure questions relate to implementation decisions, not requirements +- Verify option descriptions provide enough context for decision-making + 5. **Detect Zero-Tolerance Issues**: Identify automatic fail conditions: - Requirements not mapped to implementation tasks diff --git a/plugins/claude-constructor/agents/specification-writer.md b/plugins/claude-constructor/agents/specification-writer.md index a1e3d53..e96ae85 100644 --- a/plugins/claude-constructor/agents/specification-writer.md +++ b/plugins/claude-constructor/agents/specification-writer.md @@ -54,8 +54,40 @@ When writing a specification, you will: 5. **Analyze Existing Requirements**: - Study the Requirements Definition section thoroughly - Understand the business value, acceptance criteria, and scope boundaries - - Note any assumptions, open questions, or areas needing clarification + - Review resolved questions from requirements phase for context - Map requirements to technical components and systems + - If technical questions arise during implementation planning, document them: + + **Technical Open Questions** (add to Implementation Plan if needed): + + For questions about implementation approach with clear alternatives: + + ```markdown + ### Technical Questions + + #### [STRUCTURED] Database strategy + + Which database approach should we use for storing user preferences? + + - **Option A**: Add columns to existing users table + - **Option B**: Create separate preferences table with FK + - **Option C**: Use JSON column for flexibility + ``` + + For complex technical questions requiring discussion: + + ```markdown + #### [OPEN-ENDED] Migration strategy + + How should we handle existing data during the schema migration? + ``` + + Guidelines: + + - Prefer STRUCTURED when possible (faster resolution) + - STRUCTURED questions must have exactly 2-4 options + - Options should represent valid technical alternatives + - Questions should relate to implementation decisions, not requirements 6. **Analyze the Codebase**: - Examine existing codebase to understand what files need editing diff --git a/plugins/claude-constructor/commands/requirements-sign-off.md b/plugins/claude-constructor/commands/requirements-sign-off.md index 0b3560c..2a9bf67 100644 --- a/plugins/claude-constructor/commands/requirements-sign-off.md +++ b/plugins/claude-constructor/commands/requirements-sign-off.md @@ -18,10 +18,34 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 1. **Read State Management File**: - Read the state management file (path in $1) - Locate the specification file path + - Read the specification file to get the Requirements Definition section + +2. **Parse Open Questions**: + - Find `### Open Questions` section in Requirements Definition + - Extract questions with their type tags: `[STRUCTURED]` or `[OPEN-ENDED]` + - For STRUCTURED questions, extract options (A, B, C, D) + +3. **Resolve Structured Questions Interactively**: + - If STRUCTURED questions exist: + a. Group into batches of up to 4 questions (AskUserQuestion tool limit) + b. Use AskUserQuestion tool for each batch: + - question: The question text + - options: Array with label and description for each option + c. Update specification file: + - Move answered questions to `### Resolved Questions` section (create if needed) + - Format: Question title + "**Answer:** [selected option with description]" + - Remove the `[STRUCTURED]` tag from resolved questions + +4. **Handle Open-Ended Questions**: + - If only OPEN-ENDED questions remain: + - Rename section to `### Open Questions (Requires Discussion)` + - These will be presented in review for user to address in feedback + +5. **Present Requirements for Review**: - Present the Requirements Definition section to the user for review - Tell the user where to find the full specification: "You can review the full specification at: `{specification-file-path}`" -2. **Get User Feedback**: +6. **Get User Feedback**: - Ask the user to read and provide feedback on the Requirements Definition - If user has feedback: a. Use the requirements-definer subagent to revise requirements: @@ -33,9 +57,9 @@ You MUST follow all workflow steps below, not skipping any step and doing all st b. The subagent will detect the feedback and revise accordingly c. Return to step 1 for re-review - - If user provides explicit sign-off, proceed to step 3 + - If user provides explicit sign-off, proceed to step 7 -3. **Update Workflow Progress**: +7. **Update Workflow Progress**: - Read the state management file ($1) - Update `requirementsApproved: false` to `requirementsApproved: true` in the Workflow Progress section - Requirements sign-off is complete diff --git a/plugins/claude-constructor/commands/specification-sign-off.md b/plugins/claude-constructor/commands/specification-sign-off.md index 502ec84..e3d0eea 100644 --- a/plugins/claude-constructor/commands/specification-sign-off.md +++ b/plugins/claude-constructor/commands/specification-sign-off.md @@ -18,10 +18,34 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 1. **Read State Management File**: - Read the state management file (path in $1) - Locate the specification file path + - Read the specification file to get the Implementation Plan section + +2. **Parse Technical Questions**: + - Find `### Technical Questions` section in Implementation Plan (if exists) + - Extract questions with their type tags: `[STRUCTURED]` or `[OPEN-ENDED]` + - For STRUCTURED questions, extract options + +3. **Resolve Structured Questions Interactively**: + - If STRUCTURED questions exist: + a. Group into batches of up to 4 questions (AskUserQuestion tool limit) + b. Use AskUserQuestion tool for each batch: + - question: The question text + - options: Array with label and description for each option + c. Update specification file: + - Move answered questions to `### Resolved Technical Questions` section (create if needed) + - Format: Question title + "**Answer:** [selected option with description]" + - Remove the `[STRUCTURED]` tag from resolved questions + +4. **Handle Open-Ended Questions**: + - If only OPEN-ENDED questions remain: + - Rename section to `### Technical Questions (Requires Discussion)` + - These will be presented in review for user to address in feedback + +5. **Present Implementation Plan for Review**: - Present the Implementation Plan section to the user for review - Tell the user where to find the full specification: "You can review the full specification at: `{specification-file-path}`" -2. **Get User Feedback**: +6. **Get User Feedback**: - Ask the user to read and provide feedback on the Implementation Plan - If user has feedback: a. Use the specification-writer subagent to revise specification: @@ -33,13 +57,13 @@ You MUST follow all workflow steps below, not skipping any step and doing all st b. The subagent will detect the feedback and revise accordingly c. Return to step 1 for re-review - - If user provides explicit sign-off, proceed to step 3 + - If user provides explicit sign-off, proceed to step 7 -3. **Update Workflow Progress**: +7. **Update Workflow Progress**: - Read the state management file ($1) - Update `specificationApproved: false` to `specificationApproved: true` in the Workflow Progress section -4. **Add Issue Comment**: +8. **Add Issue Comment**: - Did you get explicit approval on the specification? If not, go back to step 2. - Read the state management file to get the issue key - Use the SlashCommand tool to execute `/create-comment [issue-key] "[specification details and assumptions]"` From 3a07bd2654605fa0f6cee8bdf5bc108ce51bfbd4 Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Tue, 20 Jan 2026 10:37:59 +0100 Subject: [PATCH 4/8] refactor: migrate SlashCommand to Skill tool SlashCommand was the legacy tool name - it has been merged into the Skill tool in current Claude Code versions. Update all references: - .claude/settings.json: permission rules now use Skill() format - Command/agent files: tool invocations use "Skill tool" wording - security-reviewer.md: tools field in frontmatter Also adds missing /implementation-summary to permissions. Co-Authored-By: Claude Opus 4.5 --- .claude/settings.json | 29 ++++++++++--------- .../agents/security-reviewer.md | 4 +-- .../commands/create-pull-request.md | 2 +- .../claude-constructor/commands/feature.md | 24 +++++++-------- .../commands/implement-increment.md | 4 +-- .../commands/issue/read-issue.md | 2 +- .../commands/review-pull-request.md | 2 +- .../commands/specification-sign-off.md | 2 +- 8 files changed, 35 insertions(+), 34 deletions(-) diff --git a/.claude/settings.json b/.claude/settings.json index 0c1c52e..81d4b7b 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,20 +1,21 @@ { "permissions": { "allow": [ - "SlashCommand(/create-state-management-file:*)", - "SlashCommand(/read-settings:*)", - "SlashCommand(/requirements-sign-off:*)", - "SlashCommand(/specification-sign-off:*)", - "SlashCommand(/git-checkout:*)", - "SlashCommand(/implement-increment:*)", - "SlashCommand(/issue:read-issue:*)", - "SlashCommand(/issue:get-issue:*)", - "SlashCommand(/issue:update-issue:*)", - "SlashCommand(/issue:create-comment:*)", - "SlashCommand(/write-end-to-end-tests:*)", - "SlashCommand(/security-review:*)", - "SlashCommand(/create-pull-request:*)", - "SlashCommand(/review-pull-request:*)" + "Skill(/create-state-management-file:*)", + "Skill(/read-settings:*)", + "Skill(/requirements-sign-off:*)", + "Skill(/specification-sign-off:*)", + "Skill(/git-checkout:*)", + "Skill(/implement-increment:*)", + "Skill(/issue:read-issue:*)", + "Skill(/issue:get-issue:*)", + "Skill(/issue:update-issue:*)", + "Skill(/issue:create-comment:*)", + "Skill(/write-end-to-end-tests:*)", + "Skill(/security-review:*)", + "Skill(/create-pull-request:*)", + "Skill(/review-pull-request:*)", + "Skill(/implementation-summary:*)" ] }, "env": { diff --git a/plugins/claude-constructor/agents/security-reviewer.md b/plugins/claude-constructor/agents/security-reviewer.md index 890baa5..bc3127f 100644 --- a/plugins/claude-constructor/agents/security-reviewer.md +++ b/plugins/claude-constructor/agents/security-reviewer.md @@ -1,7 +1,7 @@ --- name: security-reviewer description: Performs security analysis by calling the built-in /security-review command to identify vulnerabilities and security risks in the implementation -tools: SlashCommand, Read, Write +tools: Skill, Read, Write color: red --- @@ -25,7 +25,7 @@ When performing security review, you will: - If file exists, read it to count existing review iterations 3. **Execute Security Review**: - - Use the SlashCommand tool to execute `/security-review` + - Use the Skill tool to execute `/security-review` - The built-in command will analyze the codebase for security vulnerabilities 4. **Write Security Review Findings**: diff --git a/plugins/claude-constructor/commands/create-pull-request.md b/plugins/claude-constructor/commands/create-pull-request.md index 449bd59..47ebeff 100644 --- a/plugins/claude-constructor/commands/create-pull-request.md +++ b/plugins/claude-constructor/commands/create-pull-request.md @@ -43,7 +43,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 8. **Check Silent Mode for Issue Status Update**: - If `silentMode` is `false` AND `issueTrackingProvider` is NOT `"prompt"`: - - Use the SlashCommand tool to execute `/update-issue $1 "Code Review" $2` + - Use the Skill tool to execute `/update-issue $1 "Code Review" $2` - If `silentMode` is `true` OR `issueTrackingProvider` is `"prompt"`: - Log: "Silent mode: Would have updated issue $1 status to 'Code Review'" - Skip the issue update diff --git a/plugins/claude-constructor/commands/feature.md b/plugins/claude-constructor/commands/feature.md index b561758..0f63a62 100644 --- a/plugins/claude-constructor/commands/feature.md +++ b/plugins/claude-constructor/commands/feature.md @@ -108,17 +108,17 @@ Implementation progress: ## Workflow Steps -1. Create a state management file for this increment - use the SlashCommand tool to execute `/create-state-management-file $1` if the workflow was started from an issue, or the issue key if it was started from a prompt -2. Read settings - use the SlashCommand tool to execute `/read-settings [state-management-file-path]` with any optional settings arguments from $2+ (e.g., `/read-settings [path] --provider=prompt --silent=true`) -3. Read issue - check the issueTrackingProvider in the Settings section of the state management file. If not "prompt", use the SlashCommand tool to execute `/read-issue [issue-key] [state-management-file-path]`. If "prompt", skip this step as there is no external issue to read. +1. Create a state management file for this increment - use the Skill tool to execute `/create-state-management-file $1` if the workflow was started from an issue, or the issue key if it was started from a prompt +2. Read settings - use the Skill tool to execute `/read-settings [state-management-file-path]` with any optional settings arguments from $2+ (e.g., `/read-settings [path] --provider=prompt --silent=true`) +3. Read issue - check the issueTrackingProvider in the Settings section of the state management file. If not "prompt", use the Skill tool to execute `/read-issue [issue-key] [state-management-file-path]`. If "prompt", skip this step as there is no external issue to read. 4. Define requirements - Use the requirements-definer subagent to define requirements for [state-management-file-path] 5. Audit requirements - Use the requirements-definer-auditor subagent to audit requirements in [state-management-file-path]. If audit fails with critical issues, return to step 4 to address them. -6. Get sign-off on requirements. You are not allowed to go to step 7 until the user has signed off on the requirements. Use the SlashCommand tool to execute `/requirements-sign-off [state-management-file-path]` +6. Get sign-off on requirements. You are not allowed to go to step 7 until the user has signed off on the requirements. Use the Skill tool to execute `/requirements-sign-off [state-management-file-path]` 7. Write specification - Use the specification-writer subagent to write specification for [state-management-file-path] 8. Audit specification - Use the specification-writer-auditor subagent to audit specification in [state-management-file-path]. If audit fails with critical issues, return to step 7 to address them. -9. Get sign-off on specification. You are not allowed to go to step 10 until the user has signed off on the specification. Use the SlashCommand tool to execute `/specification-sign-off [state-management-file-path]` -10. Check out new branch - use the SlashCommand tool to execute `/git-checkout [issue-key] [state-management-file-path]` -11. Implement increment - use the SlashCommand tool to execute `/implement-increment [issue-key] [state-management-file-path]` +9. Get sign-off on specification. You are not allowed to go to step 10 until the user has signed off on the specification. Use the Skill tool to execute `/specification-sign-off [state-management-file-path]` +10. Check out new branch - use the Skill tool to execute `/git-checkout [issue-key] [state-management-file-path]` +11. Implement increment - use the Skill tool to execute `/implement-increment [issue-key] [state-management-file-path]` 12. Perform security review: - Use the security-reviewer subagent to analyze the implementation at [state-management-file-path] - Parse the verdict from the subagent's output (look for "**Decision**: APPROVED" or "**Decision**: NEEDS_CHANGES") @@ -127,7 +127,7 @@ Implementation progress: a. Inform user that security vulnerabilities were found b. Return to step 11 (implement increment) where agents will read claude_constructor/{issue-key}/security_review.md to understand what needs to be fixed c. Continue through steps 11-12 until APPROVED -13. Write end-to-end tests for the increment - use the SlashCommand tool to execute `/write-end-to-end-tests [state-management-file-path]` +13. Write end-to-end tests for the increment - use the Skill tool to execute `/write-end-to-end-tests [state-management-file-path]` 14. Perform code review: - Use the code-reviewer subagent to review the implementation for [state-management-file-path] - Parse the verdict from the agent's output (look for "**Decision**: APPROVED" or "**Decision**: NEEDS_CHANGES") @@ -138,15 +138,15 @@ Implementation progress: - Extract everything from that heading through the end of the output - This section must include Decision, Summary, Completed, and other details - Format contract: The agent outputs this in a specific format (see code-reviewer.md section 9) - c. Use SlashCommand tool to execute `/issue:create-comment [issue-key] "[code review summary]" [state-management-file-path]` + c. Use Skill tool to execute `/issue:create-comment [issue-key] "[code review summary]" [state-management-file-path]` d. Proceed to next step - If NEEDS_CHANGES: a. Inform the user that code review returned NEEDS_CHANGES and implementation will be revised b. Return to step 11 (implement increment) where implementation agents will read claude_constructor/{issue-key}/review.md and address the issues c. Continue through steps 11-14 again until APPROVED -15. Create pull request - use the SlashCommand tool to execute `/create-pull-request [issue-key] [state-management-file-path]` -16. Review pull request - use the SlashCommand tool to execute `/review-pull-request [issue-key] [state-management-file-path]` -17. Generate implementation summary - use the SlashCommand tool to execute `/implementation-summary [issue-key] [state-management-file-path]` +15. Create pull request - use the Skill tool to execute `/create-pull-request [issue-key] [state-management-file-path]` +16. Review pull request - use the Skill tool to execute `/review-pull-request [issue-key] [state-management-file-path]` +17. Generate implementation summary - use the Skill tool to execute `/implementation-summary [issue-key] [state-management-file-path]` **If issue tracking system operations fail**: diff --git a/plugins/claude-constructor/commands/implement-increment.md b/plugins/claude-constructor/commands/implement-increment.md index 3fe2664..926d5b7 100644 --- a/plugins/claude-constructor/commands/implement-increment.md +++ b/plugins/claude-constructor/commands/implement-increment.md @@ -17,11 +17,11 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 1. Ensure that the specification was explicitly signed off by the user. If not, go back to the specification signoff step in the larger workflow. 2. Update issue status to "In Progress": - - Use the SlashCommand tool to execute `/update-issue $1 "In Progress"` + - Use the Skill tool to execute `/update-issue $1 "In Progress"` 3. Add implementation comment: - Read the state management file ($2) to get the specification file name - - Use the SlashCommand tool to execute `/create-comment $1 "Claude Code implementation started for [specification-file-name]"` + - Use the Skill tool to execute `/create-comment $1 "Claude Code implementation started for [specification-file-name]"` 4. Understand the division of work and implement tasks: - Read specification to identify agent_ids and Dependency Graph from the Implementation Plan diff --git a/plugins/claude-constructor/commands/issue/read-issue.md b/plugins/claude-constructor/commands/issue/read-issue.md index 492ba4c..a4ce983 100644 --- a/plugins/claude-constructor/commands/issue/read-issue.md +++ b/plugins/claude-constructor/commands/issue/read-issue.md @@ -16,7 +16,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st ## Workflow Steps 1. Get issue details: - - Use the SlashCommand tool to execute `/get-issue $1 $2` + - Use the Skill tool to execute `/get-issue $1 $2` 2. Note findings in the state management file ($2) diff --git a/plugins/claude-constructor/commands/review-pull-request.md b/plugins/claude-constructor/commands/review-pull-request.md index 25b7c09..d1d93ab 100644 --- a/plugins/claude-constructor/commands/review-pull-request.md +++ b/plugins/claude-constructor/commands/review-pull-request.md @@ -37,6 +37,6 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 7. **Add pull request feedback comment** (only if silent mode and not prompt): - If `silentMode` is `false` AND `issueTrackingProvider` is NOT `"prompt"`: - - Use the SlashCommand tool to execute `/create-comment $1 "[user feedback summary and changes made in response]" $2` + - Use the Skill tool to execute `/create-comment $1 "[user feedback summary and changes made in response]" $2` - If `silentMode` is `true` OR `issueTrackingProvider` is `"prompt"`: - Log: "Silent mode: Would have added PR feedback comment to issue" diff --git a/plugins/claude-constructor/commands/specification-sign-off.md b/plugins/claude-constructor/commands/specification-sign-off.md index e3d0eea..c024da2 100644 --- a/plugins/claude-constructor/commands/specification-sign-off.md +++ b/plugins/claude-constructor/commands/specification-sign-off.md @@ -66,4 +66,4 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 8. **Add Issue Comment**: - Did you get explicit approval on the specification? If not, go back to step 2. - Read the state management file to get the issue key - - Use the SlashCommand tool to execute `/create-comment [issue-key] "[specification details and assumptions]"` + - Use the Skill tool to execute `/create-comment [issue-key] "[specification details and assumptions]"` From df28c88ddb30fb7351aadfc20cb99087062224f7 Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Tue, 20 Jan 2026 10:43:23 +0100 Subject: [PATCH 5/8] docs(workflow): clarify agent status format in implement-increment Add explicit documentation of all valid agent statuses (pending, in_progress, needs_revision, completed, failed) with descriptions. Resolves ambiguity when resuming workflows. Co-Authored-By: Claude Opus 4.5 --- .../commands/implement-increment.md | 26 ++++++++++++++----- 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/plugins/claude-constructor/commands/implement-increment.md b/plugins/claude-constructor/commands/implement-increment.md index 926d5b7..8372446 100644 --- a/plugins/claude-constructor/commands/implement-increment.md +++ b/plugins/claude-constructor/commands/implement-increment.md @@ -38,13 +38,27 @@ You MUST follow all workflow steps below, not skipping any step and doing all st - Resume agents marked as "in_progress" or "needs_revision" - Preserve existing revision counts when resuming - Log: "Resuming implementation - skipping N completed agents" - - If section does not exist, create it fresh: + - If section does not exist, create it fresh - ```markdown - ## Implementation Agents Status - - agent-1: pending (revision: 0) - - agent-2: pending (revision: 0) - ``` + **Agent Status Format**: + + ```markdown + ## Implementation Agents Status + + - agent-1: pending (revision: 0) + - agent-2: in_progress (revision: 0) + - agent-3: needs_revision (revision: 1) + - agent-4: completed (revision: 0) + - agent-5: failed (revision: 2) + ``` + + Valid statuses: + + - `pending`: Not yet started + - `in_progress`: Currently being worked on + - `needs_revision`: Audit failed, awaiting re-implementation + - `completed`: Finished and audit passed + - `failed`: Max revisions reached or unrecoverable error - Process agents in dependency order: a. Identify agents with no dependencies or whose dependencies are complete From 117c816a6dceea624ba21b3dfc1fbf0418321c65 Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Tue, 20 Jan 2026 10:44:52 +0100 Subject: [PATCH 6/8] docs(workflow): clarify ambiguous instructions - git-checkout: add explicit steps for updating workingBranch field - feature: specify timestamp format (YYYYMMDD-HHMMSS) for archives Co-Authored-By: Claude Opus 4.5 --- plugins/claude-constructor/commands/feature.md | 1 + plugins/claude-constructor/commands/git-checkout.md | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/plugins/claude-constructor/commands/feature.md b/plugins/claude-constructor/commands/feature.md index 0f63a62..a011ea9 100644 --- a/plugins/claude-constructor/commands/feature.md +++ b/plugins/claude-constructor/commands/feature.md @@ -100,6 +100,7 @@ Implementation progress: 3. If user chooses "Start Fresh": - Rename `claude_constructor/{issue-key}/` → `claude_constructor/{issue-key}-archived-{timestamp}/` + - Timestamp format: `YYYYMMDD-HHMMSS` (e.g., `ABC-123-archived-20240120-143052`) - Create fresh state file and start from step 1 4. If user chooses "Resume": diff --git a/plugins/claude-constructor/commands/git-checkout.md b/plugins/claude-constructor/commands/git-checkout.md index 1d99c17..9afbd60 100644 --- a/plugins/claude-constructor/commands/git-checkout.md +++ b/plugins/claude-constructor/commands/git-checkout.md @@ -25,4 +25,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 5. **Update Workflow Progress**: - Read the state management file ($2) - - Update `workingBranch:` to `workingBranch: feat/$1` in the Workflow Progress section + - Locate the `## Workflow Progress` section + - Find the `workingBranch:` field and replace its value with `feat/$1` + - If field doesn't exist, add `workingBranch: feat/$1` to the section + - Write the updated content back to the state management file From f2a5780d096124c92b59a64068c3fba87ebbdadf Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Tue, 20 Jan 2026 10:57:38 +0100 Subject: [PATCH 7/8] docs(workflow): fix step numbering and placeholder consistency - Standardize placeholder notation: {issue_key} not {issue-key} - Fix workflow step references across all agents and commands - Update example timestamp year from 2024 to 2026 - Add /implementation-summary to README internal commands - Remove redundant approval check in specification-sign-off Co-Authored-By: Claude Opus 4.5 --- README.md | 3 ++- .../agents/requirements-definer-auditor.md | 2 +- .../agents/requirements-definer.md | 8 ++++---- .../agents/security-reviewer.md | 2 +- .../agents/specification-writer-auditor.md | 2 +- .../agents/specification-writer.md | 2 +- plugins/claude-constructor/commands/feature.md | 16 ++++++++-------- .../commands/implement-increment.md | 4 ++-- .../commands/specification-sign-off.md | 1 - 9 files changed, 20 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 28d0036..8ea3ddd 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,7 @@ That's it. Claude Constructor will guide you through planning → approval → i | `/write-end-to-end-tests` | Implementation | | `/create-pull-request` | Review | | `/review-pull-request` | Review | +| `/implementation-summary` | Review | ## Resuming Workflows @@ -97,7 +98,7 @@ Existing workflow found for ABC-123. Resume from 'Implementation'? - Security and code review history - Git branch and PR state -**Start Fresh:** Archives the existing state to `claude_constructor/{issue-key}-archived-{timestamp}/` and begins a new workflow. +**Start Fresh:** Archives the existing state to `claude_constructor/{issue_key}-archived-{timestamp}/` and begins a new workflow. ## Agents diff --git a/plugins/claude-constructor/agents/requirements-definer-auditor.md b/plugins/claude-constructor/agents/requirements-definer-auditor.md index eb55394..40614d4 100644 --- a/plugins/claude-constructor/agents/requirements-definer-auditor.md +++ b/plugins/claude-constructor/agents/requirements-definer-auditor.md @@ -9,7 +9,7 @@ You are a strict, unbiased requirements auditor with expertise in requirements e ## Workflow Context -You are called as a audit checkpoint after requirements have been defined (step 5) and before sign-off (step 7). Your task is to ensure the requirements meet quality standards before proceeding to technical specification. +You are called as an audit checkpoint after requirements have been defined (step 4) and before sign-off (step 6). Your task is to ensure the requirements meet quality standards before proceeding to technical specification. You may also be called to audit requirements that have been revised based on previous feedback, in which case you should analyze both the original issues and how well the revisions addressed them. diff --git a/plugins/claude-constructor/agents/requirements-definer.md b/plugins/claude-constructor/agents/requirements-definer.md index caa83e8..55be734 100644 --- a/plugins/claude-constructor/agents/requirements-definer.md +++ b/plugins/claude-constructor/agents/requirements-definer.md @@ -9,7 +9,7 @@ You are an expert requirements analyst with deep experience in software engineer ## Workflow Context -You are called as step 5 in a feature implementation workflow. The state management file provided to you will contain: +You are called as step 4 in a feature implementation workflow. The state management file provided to you will contain: - Issue details and context from the issue tracker - Project settings and configuration @@ -152,11 +152,11 @@ Create a well-structured markdown document with clear headers and subsections. U ## Workflow Integration -Remember you are step 5 in the workflow: +Remember you are step 4 in the workflow: -- Step 4 (read-issue) has provided the issue context +- Step 3 (read-issue) has provided the issue context - Your task is to define the requirements -- Step 6 (requirements-sign-off) will review your work +- Step 5 (audit) and step 6 (requirements-sign-off) will review your work - Step 7 (write-specification) will use your requirements to create an implementation plan The requirements you define will be the foundation for all subsequent implementation work, so they must be complete, clear, and focused on business value. diff --git a/plugins/claude-constructor/agents/security-reviewer.md b/plugins/claude-constructor/agents/security-reviewer.md index bc3127f..ed3e10c 100644 --- a/plugins/claude-constructor/agents/security-reviewer.md +++ b/plugins/claude-constructor/agents/security-reviewer.md @@ -9,7 +9,7 @@ You are a security review coordinator that performs security analysis on impleme ## Workflow Context -You are called after implementation (step 12) to ensure the code is secure before proceeding to end-to-end tests (step 14). Your task is to run the built-in `/security-review` command and persist the findings for tracking. +You are called after implementation (step 11) to ensure the code is secure before proceeding to end-to-end tests (step 13). Your task is to run the built-in `/security-review` command and persist the findings for tracking. ## Security Review Process diff --git a/plugins/claude-constructor/agents/specification-writer-auditor.md b/plugins/claude-constructor/agents/specification-writer-auditor.md index a57b015..9215468 100644 --- a/plugins/claude-constructor/agents/specification-writer-auditor.md +++ b/plugins/claude-constructor/agents/specification-writer-auditor.md @@ -9,7 +9,7 @@ You are a strict, unbiased technical specification auditor with expertise in arc ## Workflow Context -You are called as a audit checkpoint after specification writing (step 8) and before sign-off (step 10). Your task is to ensure the implementation plan is technically sound and ready for execution by automated agents. +You are called as an audit checkpoint after specification writing (step 7) and before sign-off (step 9). Your task is to ensure the implementation plan is technically sound and ready for execution by automated agents. You may also be called to audit specifications that have been revised based on previous feedback, in which case you should analyze both the original issues and how well the revisions addressed them. diff --git a/plugins/claude-constructor/agents/specification-writer.md b/plugins/claude-constructor/agents/specification-writer.md index e96ae85..2e7b7d1 100644 --- a/plugins/claude-constructor/agents/specification-writer.md +++ b/plugins/claude-constructor/agents/specification-writer.md @@ -129,7 +129,7 @@ When writing a specification, you will: [Detailed breakdown of what each agent should implement] ``` - Note: Do not include end-to-end tests in the implementation plan, as they are handled in workflow step 11. + Note: Do not include end-to-end tests in the implementation plan, as they are handled in workflow step 13. 10. **Quality Checks**: Before finalizing, verify your specification: diff --git a/plugins/claude-constructor/commands/feature.md b/plugins/claude-constructor/commands/feature.md index a011ea9..a6920dd 100644 --- a/plugins/claude-constructor/commands/feature.md +++ b/plugins/claude-constructor/commands/feature.md @@ -45,7 +45,7 @@ Before starting the workflow, check if a previous workflow exists for this issue ### Detection Algorithm -Check if `claude_constructor/{issue-key}/state_management.md` exists. If it does, parse the file and determine the resume point using this algorithm (check in reverse order, first match wins): +Check if `claude_constructor/{issue_key}/state_management.md` exists. If it does, parse the file and determine the resume point using this algorithm (check in reverse order, first match wins): | Check | Condition | Resume at | |-------|-----------|-----------| @@ -83,24 +83,24 @@ Implementation progress: 1. Display progress summary: ```text - Progress for {issue-key}: + Progress for {issue_key}: - [x] Requirements defined + approved - [x] Specification written + approved - [ ] Implementation ← Resume point ``` 2. Use AskUserQuestion tool: - - question: "Existing workflow found for {issue-key}. Resume from '{step-name}'?" + - question: "Existing workflow found for {issue_key}. Resume from '{step_name}'?" - header: "Resume" - options: - label: "Resume (Recommended)" - description: "Continue from {step-name}, preserving existing progress" + description: "Continue from {step_name}, preserving existing progress" - label: "Start Fresh" description: "Archive existing state and begin new workflow" 3. If user chooses "Start Fresh": - - Rename `claude_constructor/{issue-key}/` → `claude_constructor/{issue-key}-archived-{timestamp}/` - - Timestamp format: `YYYYMMDD-HHMMSS` (e.g., `ABC-123-archived-20240120-143052`) + - Rename `claude_constructor/{issue_key}/` → `claude_constructor/{issue_key}-archived-{timestamp}/` + - Timestamp format: `YYYYMMDD-HHMMSS` (e.g., `ABC-123-archived-20260120-143052`) - Create fresh state file and start from step 1 4. If user chooses "Resume": @@ -126,7 +126,7 @@ Implementation progress: - If APPROVED: proceed to next step - If NEEDS_CHANGES: a. Inform user that security vulnerabilities were found - b. Return to step 11 (implement increment) where agents will read claude_constructor/{issue-key}/security_review.md to understand what needs to be fixed + b. Return to step 11 (implement increment) where agents will read claude_constructor/{issue_key}/security_review.md to understand what needs to be fixed c. Continue through steps 11-12 until APPROVED 13. Write end-to-end tests for the increment - use the Skill tool to execute `/write-end-to-end-tests [state-management-file-path]` 14. Perform code review: @@ -143,7 +143,7 @@ Implementation progress: d. Proceed to next step - If NEEDS_CHANGES: a. Inform the user that code review returned NEEDS_CHANGES and implementation will be revised - b. Return to step 11 (implement increment) where implementation agents will read claude_constructor/{issue-key}/review.md and address the issues + b. Return to step 11 (implement increment) where implementation agents will read claude_constructor/{issue_key}/review.md and address the issues c. Continue through steps 11-14 again until APPROVED 15. Create pull request - use the Skill tool to execute `/create-pull-request [issue-key] [state-management-file-path]` 16. Review pull request - use the Skill tool to execute `/review-pull-request [issue-key] [state-management-file-path]` diff --git a/plugins/claude-constructor/commands/implement-increment.md b/plugins/claude-constructor/commands/implement-increment.md index 8372446..6837250 100644 --- a/plugins/claude-constructor/commands/implement-increment.md +++ b/plugins/claude-constructor/commands/implement-increment.md @@ -26,10 +26,10 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 4. Understand the division of work and implement tasks: - Read specification to identify agent_ids and Dependency Graph from the Implementation Plan - Check for code review feedback: - - Determine code-review file path: `claude_constructor/{issue-key}/review.md` (where issue-key is $1) + - Determine code-review file path: `claude_constructor/{issue_key}/review.md` (where issue-key is $1) - If file exists: Read the latest review (most recent "Review #N" section) to understand what needs fixing - If this is a revision (code-review file exists), prioritize addressing review issues over spec additions - - Note: Subagents will automatically check for and read claude_constructor/{issue-key}/review.md if it exists - no need to pass review content explicitly + - Note: Subagents will automatically check for and read claude_constructor/{issue_key}/review.md if it exists - no need to pass review content explicitly - **Check for existing Implementation Agents Status** (resume support): - Read the state management file ($2) - If `## Implementation Agents Status` section already exists: diff --git a/plugins/claude-constructor/commands/specification-sign-off.md b/plugins/claude-constructor/commands/specification-sign-off.md index c024da2..4d93bb9 100644 --- a/plugins/claude-constructor/commands/specification-sign-off.md +++ b/plugins/claude-constructor/commands/specification-sign-off.md @@ -64,6 +64,5 @@ You MUST follow all workflow steps below, not skipping any step and doing all st - Update `specificationApproved: false` to `specificationApproved: true` in the Workflow Progress section 8. **Add Issue Comment**: - - Did you get explicit approval on the specification? If not, go back to step 2. - Read the state management file to get the issue key - Use the Skill tool to execute `/create-comment [issue-key] "[specification details and assumptions]"` From be5086d4e82acc15a52346b49f08ec8dacf2b0e5 Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Tue, 20 Jan 2026 11:06:19 +0100 Subject: [PATCH 8/8] docs(workflow): improve command specifications from review feedback - Add missing state-management-file-path ($2) argument to Skill commands - Document option parsing rules for STRUCTURED questions (canonical format, accepted variants, validation with graceful fallback) - Add explicit batching loop logic for AskUserQuestion tool - Replace placeholder with dynamic summary generation in review-pull-request Co-Authored-By: Claude Opus 4.5 --- .../commands/implement-increment.md | 4 +- .../commands/requirements-sign-off.md | 42 +++++++++++++++--- .../commands/review-pull-request.md | 11 +++-- .../commands/specification-sign-off.md | 44 +++++++++++++++---- 4 files changed, 81 insertions(+), 20 deletions(-) diff --git a/plugins/claude-constructor/commands/implement-increment.md b/plugins/claude-constructor/commands/implement-increment.md index 6837250..37090e8 100644 --- a/plugins/claude-constructor/commands/implement-increment.md +++ b/plugins/claude-constructor/commands/implement-increment.md @@ -17,11 +17,11 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 1. Ensure that the specification was explicitly signed off by the user. If not, go back to the specification signoff step in the larger workflow. 2. Update issue status to "In Progress": - - Use the Skill tool to execute `/update-issue $1 "In Progress"` + - Use the Skill tool to execute `/update-issue $1 "In Progress" $2` 3. Add implementation comment: - Read the state management file ($2) to get the specification file name - - Use the Skill tool to execute `/create-comment $1 "Claude Code implementation started for [specification-file-name]"` + - Use the Skill tool to execute `/create-comment $1 "Claude Code implementation started for [specification-file-name]" $2` 4. Understand the division of work and implement tasks: - Read specification to identify agent_ids and Dependency Graph from the Implementation Plan diff --git a/plugins/claude-constructor/commands/requirements-sign-off.md b/plugins/claude-constructor/commands/requirements-sign-off.md index 2a9bf67..4a99afe 100644 --- a/plugins/claude-constructor/commands/requirements-sign-off.md +++ b/plugins/claude-constructor/commands/requirements-sign-off.md @@ -23,16 +23,44 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 2. **Parse Open Questions**: - Find `### Open Questions` section in Requirements Definition - Extract questions with their type tags: `[STRUCTURED]` or `[OPEN-ENDED]` - - For STRUCTURED questions, extract options (A, B, C, D) + - For STRUCTURED questions, extract options using these rules: + + **Canonical format** (from requirements-definer): + + ```markdown + - **Option A**: Description text + - **Option B**: Description text + ``` + + **Also accept these variants** (normalize to canonical): + + - `- **Option A**: text` (canonical) + - `- Option A: text` + - `- A. text` + - `- A) text` + - `- A: text` + + Extract: label (A/B/C/D) and description text. + + **Validation**: + + - STRUCTURED questions must have at least 2 options + - If no options found: log warning "No options found for STRUCTURED question: [title]", treat as OPEN-ENDED + - If only 1 option found: log warning "Only 1 option found for STRUCTURED question: [title]", treat as OPEN-ENDED 3. **Resolve Structured Questions Interactively**: - If STRUCTURED questions exist: - a. Group into batches of up to 4 questions (AskUserQuestion tool limit) - b. Use AskUserQuestion tool for each batch: - - question: The question text - - options: Array with label and description for each option - c. Update specification file: - - Move answered questions to `### Resolved Questions` section (create if needed) + a. Collect all STRUCTURED questions into a list (preserving original order) + b. Process in sequential batches of up to 4 questions each: + - While unprocessed STRUCTURED questions remain: + 1. Take the next batch (up to 4 questions) + 2. Call AskUserQuestion tool with the batch: + - question: The question text + - options: Array with label and description for each option + 3. Await and collect user responses for all questions in batch + 4. Continue to next batch + c. After all batches complete, update specification file: + - Move all answered questions to `### Resolved Questions` section (create if needed) - Format: Question title + "**Answer:** [selected option with description]" - Remove the `[STRUCTURED]` tag from resolved questions diff --git a/plugins/claude-constructor/commands/review-pull-request.md b/plugins/claude-constructor/commands/review-pull-request.md index d1d93ab..e491ac3 100644 --- a/plugins/claude-constructor/commands/review-pull-request.md +++ b/plugins/claude-constructor/commands/review-pull-request.md @@ -35,8 +35,13 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 6. Repeat steps 3 through 5 until the user approves the pull request. You are not allowed to approve the pull request yourself. -7. **Add pull request feedback comment** (only if silent mode and not prompt): +7. **Add pull request feedback comment** (only if not silent mode and not prompt): - If `silentMode` is `false` AND `issueTrackingProvider` is NOT `"prompt"`: - - Use the Skill tool to execute `/create-comment $1 "[user feedback summary and changes made in response]" $2` + - Generate a concise feedback summary from steps 3-6: + - List reviewer comments/feedback received + - Describe changes made in response to each + - Note any questions answered + - Format as a brief markdown summary (e.g., "**PR Feedback Addressed:**\n- Fixed X per reviewer comment\n- Updated Y as requested") + - Use the Skill tool to execute `/create-comment $1 "{generated-feedback-summary}" $2` - If `silentMode` is `true` OR `issueTrackingProvider` is `"prompt"`: - - Log: "Silent mode: Would have added PR feedback comment to issue" + - Log: "Skipping PR feedback comment (silent mode or prompt provider)" diff --git a/plugins/claude-constructor/commands/specification-sign-off.md b/plugins/claude-constructor/commands/specification-sign-off.md index 4d93bb9..913aa70 100644 --- a/plugins/claude-constructor/commands/specification-sign-off.md +++ b/plugins/claude-constructor/commands/specification-sign-off.md @@ -23,16 +23,44 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 2. **Parse Technical Questions**: - Find `### Technical Questions` section in Implementation Plan (if exists) - Extract questions with their type tags: `[STRUCTURED]` or `[OPEN-ENDED]` - - For STRUCTURED questions, extract options + - For STRUCTURED questions, extract options using these rules: + + **Canonical format** (from specification-writer): + + ```markdown + - **Option A**: Description text + - **Option B**: Description text + ``` + + **Also accept these variants** (normalize to canonical): + + - `- **Option A**: text` (canonical) + - `- Option A: text` + - `- A. text` + - `- A) text` + - `- A: text` + + Extract: label (A/B/C/D) and description text. + + **Validation**: + + - STRUCTURED questions must have at least 2 options + - If no options found: log warning "No options found for STRUCTURED question: [title]", treat as OPEN-ENDED + - If only 1 option found: log warning "Only 1 option found for STRUCTURED question: [title]", treat as OPEN-ENDED 3. **Resolve Structured Questions Interactively**: - If STRUCTURED questions exist: - a. Group into batches of up to 4 questions (AskUserQuestion tool limit) - b. Use AskUserQuestion tool for each batch: - - question: The question text - - options: Array with label and description for each option - c. Update specification file: - - Move answered questions to `### Resolved Technical Questions` section (create if needed) + a. Collect all STRUCTURED questions into a list (preserving original order) + b. Process in sequential batches of up to 4 questions each: + - While unprocessed STRUCTURED questions remain: + 1. Take the next batch (up to 4 questions) + 2. Call AskUserQuestion tool with the batch: + - question: The question text + - options: Array with label and description for each option + 3. Await and collect user responses for all questions in batch + 4. Continue to next batch + c. After all batches complete, update specification file: + - Move all answered questions to `### Resolved Technical Questions` section (create if needed) - Format: Question title + "**Answer:** [selected option with description]" - Remove the `[STRUCTURED]` tag from resolved questions @@ -65,4 +93,4 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 8. **Add Issue Comment**: - Read the state management file to get the issue key - - Use the Skill tool to execute `/create-comment [issue-key] "[specification details and assumptions]"` + - Use the Skill tool to execute `/create-comment [issue-key] "[specification details and assumptions]" $1`