Hurblat avatar

claude-constructor

A workflow automation system that helps Claude Code implement features systematically with built-in planning, validation, and review steps

version
1.3.1
GitHub stars
15

Install

/plugin install claude-constructor@hurblat-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Hurblat/claude-constructor.

Contents

Discovered from source

Commands 15

Create Pull Request Command

Purpose

Create pull request for increment implemented to satisfy the issue. Add, commit, push code for the finished increment. Create Pull request in GitHub using the gh CLI. This command is called by an orchestrating command, and is one of the steps in a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Workflow Steps

  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 claude_constructor folder.

  3. Create a git commit using the guidelines in @docs/git-commit.md

  4. Push the commit using git push

  5. Read the Settings section in the state management file ($2)

  6. Check Silent Mode for Pull Request Creation:

    • If silentMode is false:
      • Create a pull request using gh pr create --title "feat: $1 [brief description from commit]" --base [default branch name] --head $(git branch --show-current)
    • If silentMode is true:
      • Log: "Silent mode: Would have created PR with title 'feat: [issue key] [brief description]'"
      • Skip the actual PR creation
  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 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

Create State Management File Command

Purpose

Create a state management file and add the issue key. These instructions are read and followed as part of a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Workflow Steps

  1. Create the workflow directory for this issue using mkdir -p claude_constructor/$1

  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}

## Workflow Progress
- requirementsApproved: false
- specificationApproved: false
- workingBranch:
- pullRequestUrl:

Feature Implementation Command

Purpose

This command guides the implementation of new functionality using minimal iteration cycles. Each workflow run should implement the smallest possible increment that provides measurable value while maintaining the system's quality standards.

You are responsible for making sure all steps are done according to the workflow steps description below.

IMPORTANT: All steps MUST complete, and they must be completed in the order described below. You are only allowed to move to the next step after the previous step has completed.

The issue key or prompt for the feature to implement is $1.

Create a TODO list for the workflow steps, and follow it.

Arguments

  • $1: Issue key or feature prompt (required)
  • $2+: Optional settings in format --provider=<value> or --silent=<value>
    • --provider: Override issue tracking provider (linear, jira, or prompt)
    • --silent: Override silent mode (true or false)

Pre-Processing

Before starting the workflow for user prompts, create an issue key based on $1:

  • 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.

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):

CheckConditionResume at
1implementation_summary.md existsComplete - offer to start fresh
2pullRequestUrl is set (not empty)Step 16 (review PR)
3review.md latest review has APPROVEDStep 15 (create PR)
4review.md latest review has NEEDS_CHANGESStep 11 (re-implement, code review loop)
5review.md exists (any content)Step 14 (code review - was interrupted)
6security_review.md latest has APPROVEDStep 13 (write E2E tests)
7security_review.md latest has NEEDS_CHANGESStep 11 (re-implement, security loop)
8security_review.md exists (any content)Step 12 (security review - was interrupted)
9Agent statuses all "completed"Step 12 (security review)
10Agent statuses exist with incompleteStep 11 (continue implementation)
11workingBranch is set, no agent statusesStep 11 (start implementation)
12specificationApproved: trueStep 10 (git checkout)
13Implementation Plan section exists in specificationStep 9 (spec sign-off)
14requirementsApproved: trueStep 7 (write spec)
15Requirements Definition section exists in specificationStep 6 (req sign-off)
16Settings section existsStep 4 (define requirements)
17State file exists onlyStep 2 (read settings)

Implementation Progress Display

For implementation resume (check 10), show detailed agent progress:

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:

    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}/
      • 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":

    • Skip to the detected resume step
    • For step 11 resume, /implement-increment will handle skipping completed agents

Workflow Steps

  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 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 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")
    • 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 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:
    • 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: a. Extract issue key from state management file b. Extract code review summary from agent output:
      • Look for the section starting with "## Code Review Summary"
      • 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 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 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:

  • Continue with local specification files
  • Log issue tracking system errors but don't block development
  • Manually update issue status if needed

Git Checkout Command

Purpose

Check out a new git branch to be ready for implementation start. These instructions are read and followed as part of a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Workflow Steps

  1. Read the Settings section in the state management file ($2) to get the default branch name

  2. Run git checkout [default branch name]

  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)
    • 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

Implement Increment Command

Purpose

Implement the increment using the specification in the state management file. These instructions are read and followed as part of a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Workflow Steps

  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" $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]" $2
  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)
      • 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
    • 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

    Agent Status Format:

    ## 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 b. Update their status to "in_progress" in Implementation Agents Status c. Spawn those agents in parallel using the increment-implementer subagent via Task tool d. Pass to each subagent: the agent_id and state management file path e. Monitor for completion signals ("AGENT_COMPLETE: [agent_id]") f. When an agent reports completion, invoke increment-implementer-auditor subagent via Task tool g. Pass to auditor: the agent_id and state management file path h. Wait for audit result (AUDIT_PASSED/AUDIT_FAILED) i. If audit passes, update status to "completed" in Implementation Agents Status j. If audit fails:

      • Update status to "needs_revision" in Implementation Agents Status
      • Extract specific feedback from audit report
      • Re-spawn the increment-implementer subagent with the feedback
      • Pass: agent_id, state management file path, and "Validator/Auditor feedback: [specific issues]"
      • Increment revision counter for tracking
      • Repeat audit cycle until pass or max revisions reached (3 attempts)
      • If max revisions reached, mark as "failed" and handle as agent failure k. Repeat until all agents are complete
    • Handle agent failures:

      • If an agent reports failure, mark it as "failed" in Implementation Agents Status
      • Do not spawn agents that depend on failed agents
      • Report the failure chain to the user
    • When all agent_ids are complete, implementation is finished

This part of the workflow is done when

  • All subagents are complete and have passed their audits
  • All audit feedback has been addressed through the revision process
  • Single behavior is fully implemented, both on the backend and the frontend
  • All unit and integration tests pass
  • All quality gates pass (see @CLAUDE.md for commands)
  • No breaking changes introduced
  • No test failures introduced in areas of the code unrelated to this increment
  • Feature works in both development and build modes
  • Business rules are enforced consistently
  • Implementation strictly adheres to specification without scope creep
  • No unnecessary code or over-engineering detected in audits

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:

    • 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:

    # 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
    
    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
    
    **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/N/A}
    
    ### Code Review
    
    - **Iterations**: {count}
    - **Final Status**: {APPROVED/N/A}
    
    ## 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

Create Issue Comment Command

Purpose

Add a comment to an issue in the configured issue tracking system. This command is called by other orchestrating commands, and is one of the steps in a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Arguments

  • $1: Issue key (required)
  • $2: Comment text (required)
  • $3: Path to state management file (required)

Workflow Steps

  1. Read Settings from State Management File:

    • Read the Settings section from the state management file ($3)
    • Extract issueTrackingProvider and silentMode values
    • If Settings section is missing, fail with error: "Settings not found in state management file. Run /read-settings first."
  2. Validate Provider Configuration:

    • If issueTrackingProvider is "linear":
      • Check that Linear MCP tools are available
      • If NOT available: FAIL with error: "Provider is 'linear' but Linear MCP tools are not configured. Please configure Linear MCP or update settings with /read-settings --provider=prompt"
    • If issueTrackingProvider is "jira":
      • Check that Jira MCP tools are available
      • If NOT available: FAIL with error: "Provider is 'jira' but Jira MCP tools are not configured. Please configure Jira MCP or update settings with /read-settings --provider=prompt"
  3. Check Silent Mode or Prompt Issue Provider:

    • If silentMode is true OR issueTrackingProvider is "prompt":
      • Log the comment operation locally: "Silent mode: Would have added comment to $1: $2"
      • Skip the actual API call (step 4)
      • Continue to step 5
  4. Execute Create Comment Operation (only if silentMode is false and issueTrackingProvider is not "prompt"):

For Linear Provider ("linear")

  • Use linear:create_comment with $1 (issue ID) and $2 (comment text)
  • Add the comment to the specified issue

For Jira Provider ("jira")

  • Use jira:add_comment_to_issue with $1 (issue key) and $2 (comment text)
  • Add the comment to the specified issue
  1. Output Results: Display confirmation of the comment creation:

    • Issue: $1
    • Comment Added: $2
    • Result: Success/Failure (or "Skipped - Silent Mode" if applicable)
  2. Error Handling: If the issue operation fails, log the error but continue gracefully

Get Issue Command

Purpose

Retrieve issue details from the configured issue tracking system for a given issue key. This command is called by other orchestrating commands, and is one of the steps in a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Arguments

  • $1: Issue key (required)
  • $2: Path to state management file (required)

Workflow Steps

  1. Read Settings from State Management File:

    • Read the Settings section from the state management file ($2)
    • Extract issueTrackingProvider value
    • If Settings section is missing or issueTrackingProvider is not set, fail with error: "Settings not found in state management file. Run /read-settings first."
  2. Validate Provider Configuration:

    • If issueTrackingProvider is "linear":
      • Check that Linear MCP tools are available
      • If NOT available: FAIL with error: "Provider is 'linear' but Linear MCP tools are not configured. Please configure Linear MCP or update settings with /read-settings --provider=prompt"
    • If issueTrackingProvider is "jira":
      • Check that Jira MCP tools are available
      • If NOT available: FAIL with error: "Provider is 'jira' but Jira MCP tools are not configured. Please configure Jira MCP or update settings with /read-settings --provider=prompt"
    • If issueTrackingProvider is "prompt":
      • Log error: "get-issue should not be called for prompt provider"
      • Skip to step 4
  3. Execute Get Issue Operation:

    Based on the issueTrackingProvider value from the state management file:

    For Linear Provider ("linear")

    • Use linear:get_issue with $1 (issue key)
    • Retrieve issue key, ID, title, and description

    For Jira Provider ("jira")

    • Use jira:get_issue with $1 (issue key)
    • Retrieve issue key, ID, title, and description
  4. Output Results: Display the issue information in this format:

    • Key: $1
    • ID: Issue ID
    • Title: Issue title
    • Description: Issue description
  5. Error Handling: If the issue operation fails, log the error but continue gracefully

Read Issue Command

Purpose

Read issue from the configured issue tracking system and add the information to the state management file. These instructions are read and followed as part of a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Workflow Steps

  1. Get issue details:

    • Use the Skill tool to execute /get-issue $1 $2
  2. Note findings in the state management file ($2)

Create a new section called ## Issue Information, with information on this format:

  • Key: $1
  • ID: Issue ID (from get-issue response)
  • Title: Issue title (from get-issue response)
  • Description: Issue description (from get-issue response)

Update Issue Command

Purpose

Update the status of an issue in the configured issue tracking system. This command is called by other orchestrating commands, and is one of the steps in a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Expected status values: "In Progress", "Code Review"

Arguments

  • $1: Issue key (required)
  • $2: Status to set (required)
  • $3: Path to state management file (required)

Workflow Steps

  1. Read Settings from State Management File:

    • Read the Settings section from the state management file ($3)
    • Extract issueTrackingProvider and silentMode values
    • If Settings section is missing, fail with error: "Settings not found in state management file. Run /read-settings first."
  2. Validate Provider Configuration:

    • If issueTrackingProvider is "linear":
      • Check that Linear MCP tools are available
      • If NOT available: FAIL with error: "Provider is 'linear' but Linear MCP tools are not configured. Please configure Linear MCP or update settings with /read-settings --provider=prompt"
    • If issueTrackingProvider is "jira":
      • Check that Jira MCP tools are available
      • If NOT available: FAIL with error: "Provider is 'jira' but Jira MCP tools are not configured. Please configure Jira MCP or update settings with /read-settings --provider=prompt"
  3. Check Silent Mode or Prompt Issue Provider:

    • If silentMode is true OR issueTrackingProvider is "prompt":
      • Log the status update operation locally: "Silent mode: Would have updated $1 status to '$2'"
      • Skip the actual API calls (step 4)
      • Continue to step 5
  4. Execute Update Status Operation (only if silentMode is false and issueTrackingProvider is not "prompt"):

For Linear Provider ("linear")

  • First, use linear:list_issue_statuses to get all available statuses for $1
  • Find the best match for $2 (handles typos/variations)
  • Use linear:update_issue with $1 to set the issue to the matched status
  • If no exact match is found, use the closest matching status name

For Jira Provider ("jira")

  • First, use jira:get_transitions_for_issue with $1 to get all available columns
  • Find the best match for $2 (handles typos/variations)
  • Use jira:transition_issue with $1 to move the issue to the matched transition
  • If no exact match is found, use the closest matching status name
  1. Output Results: Display confirmation of the status update:

    • Issue: $1
    • Previous Status: [if available]
    • New Status: $2
    • Result: Success/Failure (or "Skipped - Silent Mode" if applicable)
  2. Error Handling: If the issue operation fails, log the error but continue gracefully

Read Settings Command

Purpose

Read Claude Constructor settings and add them to the state management file. Settings are determined by command arguments or auto-detection. These instructions are read and followed as part of a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Arguments

  • $1: Path to state management file (required)
  • $2+: Optional settings in format --provider=<value> or --silent=<value>

Workflow Steps

  1. Parse optional arguments ($2, $3, etc.) to extract settings overrides:

    • Look for --provider=<value> (valid: "linear", "jira", "prompt")
    • Look for --silent=<value> (valid: "true", "false")
  2. Determine settings in this priority order:

    Issue Tracking Provider:

    • If --provider=<value> argument provided:
      • Validate it's one of: "linear", "jira", "prompt"
      • If "linear": Check that Linear MCP tools are available (try calling linear:list_teams or similar)
        • If NOT available: FAIL with error: "Provider set to 'linear' but Linear MCP tools are not configured. Please configure Linear MCP or use --provider=prompt"
      • If "jira": Check that Jira MCP tools are available (try calling jira:get_projects or similar)
        • If NOT available: FAIL with error: "Provider set to 'jira' but Jira MCP tools are not configured. Please configure Jira MCP or use --provider=prompt"
      • If "prompt": No validation needed
      • Use the validated provider value
    • Otherwise, auto-detect:
      • If Linear MCP tools are available → "linear"
      • If Jira MCP tools are available → "jira"
      • Otherwise → "prompt"

    Default Branch:

    • Auto-detect by running: git symbolic-ref refs/remotes/origin/HEAD --short
    • Parse the output to extract the branch name after "origin/" (e.g., "origin/main" → "main")
    • If that fails, try: git rev-parse --abbrev-ref origin/HEAD and parse similarly
    • If both fail, default to "main"

    Silent Mode:

    • If --silent=<value> argument provided, use it
    • Otherwise, default to "false"
  3. Read the state management file ($1) to check if Settings section already exists

  4. If Settings section exists:

    • Update the existing Settings section with the determined values
    • Use Edit tool to replace the Settings section
  5. If Settings section does not exist:

    • Add a new Settings section to the state management file using Edit tool

    • Format:

      ## Settings
      - issueTrackingProvider: [value]
      - defaultBranch: [value]
      - silentMode: [value]
      

Requirements Sign-Off Command

Purpose

Get sign-off on the requirements for the increment to be implemented. These instructions are read and followed as part of a larger workflow. 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 (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 using these rules:

      Canonical format (from requirements-definer):

      - **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. 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, use requirements-definer subagent to update specification:
      State management file: $1
      Resolved questions:
      - [Question title]: [Selected option with description]
      - [Question title]: [Selected option with description]
      

      The subagent will move answered questions to ### Resolved Questions section

  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}"
  6. Get User Approval:

    • Use AskUserQuestion tool with:

      • question: "Do you approve these requirements?"
      • header: "Requirements"
      • options:
        • label: "Approve" description: "Requirements are complete and accurate, proceed to implementation planning"
        • label: "Request changes" description: "I have feedback to provide"
    • If user selects "Approve": proceed to step 7

    • If user selects "Request changes" or provides feedback via "Other": a. Use the requirements-definer subagent to revise requirements:

      State management file: $1
      User feedback to address: [user's feedback verbatim]
      

      b. The subagent will detect the feedback and revise accordingly c. Return to step 1 for re-review

  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

Review Pull Request Command

Purpose

Review pull request for the increment implemented to satisfy the issue. This command is called by an orchestrating command, and is one of the steps in a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Workflow Steps

  1. Load Settings: Read the Settings section in the state management file ($2)

  2. Check Silent Mode:

    • If silentMode is true:
      • Log: "Silent mode: Skipping PR review monitoring and comments"
      • Skip to step 7
    • If silentMode is false:
      • Continue with normal PR review workflow (steps 3-6)
  3. Monitor the pull request for comments and/or reviews. Use gh api repos/{OWNER}/{REPO}/pulls/{PR_NUMBER}/comments --jq '.[] | {author: .user.login, body: .body, path: .path, line: .line}'

  4. For each unaddressed comment:

    • Implement the requested changes
    • Commit and push changes. Read @docs/git-commit.md for commit guidelines. Check that there are not unstaged changes you haven't considered.
  5. Add a reply to each addressed comment explaining how the requested changes were addressed (or if it was a question, your response to the question): gh api repos/{OWNER}/{REPO}/pulls/{PR_NUMBER}/comments --method POST --field body="Your message here" --field in_reply_to={COMMENT_ID_NUMBER}

    • Do not edit existing comments
    • Reply to specific comments, do not make general PR comments
  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 not silent mode and not prompt):

    • If silentMode is false AND issueTrackingProvider is NOT "prompt":
      • 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: "Skipping PR feedback comment (silent mode or prompt provider)"

Specification Sign-Off Command

Purpose

Get sign-off on the specification for the increment to be implemented. These instructions are read and followed as part of a larger workflow. 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 (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 using these rules:

      Canonical format (from specification-writer):

      - **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. 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, use specification-writer subagent to update specification:
      State management file: $1
      Resolved questions:
      - [Question title]: [Selected option with description]
      - [Question title]: [Selected option with description]
      

      The subagent will move answered questions to ### Resolved Technical Questions section

  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}"
  6. Get User Approval:

    • Use AskUserQuestion tool with:

      • question: "Do you approve this implementation plan?"
      • header: "Specification"
      • options:
        • label: "Approve" description: "Implementation plan is complete and accurate, proceed to implementation"
        • label: "Request changes" description: "I have feedback to provide"
    • If user selects "Approve": proceed to step 7

    • If user selects "Request changes" or provides feedback via "Other": a. Use the specification-writer subagent to revise specification:

      State management file: $1
      User feedback to address: [user's feedback verbatim]
      

      b. The subagent will detect the feedback and revise accordingly c. Return to step 1 for re-review

  7. Update Workflow Progress:

    • Read the state management file ($1)
    • Update specificationApproved: false to specificationApproved: true in the Workflow Progress section
  8. Add Issue Comment (skip if provider is "prompt"):

    • Read the state management file to get the issue key and provider
    • If provider is NOT "prompt": Use the Skill tool to execute /create-comment [issue-key] "[specification details and assumptions]" $1
  9. Specification sign-off is complete

Write End-To-End Tests for Increment Command

Purpose

Write end-to-end tests for the implemented increment using the specification linked in the state management file ($1). This command is called by an orchestrating command, and is one of the steps in a larger workflow. You MUST follow all workflow steps below, not skipping any step and doing all steps in order.

Workflow Steps

  1. Understand how the increment has been implemented, and the context surrounding it:

    • Read specification to learn the business value that the increment is delivering, and what the plan for implementing that value is
    • Read the code implemented, using git to identify what has been added
  2. Write a plan for how to test the necessary behavior

  3. Write end-to-end tests that cover your plan

This part of the workflow is done when

  • Frontend behavior is verified using end-to-end tests
  • All unit, integration, and end-to-end tests pass (100% coverage of user behavior expected)
  • All quality gates pass (see @CLAUDE.md for commands)
  • No test failures introduced in areas of the code unrelated to this increment

Agents 8

You review code changes for the active increment and provide a verdict of NEEDS_CHANGES or APPROVED.

Input

You receive:

  • A state management file path

Workflow

1. Parse Input

Extract the state management file path from the prompt.

2. Read Context

  1. Read state management file to understand the context for what you need to review
  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: 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

Before analyzing the implementation, quickly understand the project structure and quality requirements:

Quality Gates Discovery:

  • Check @CLAUDE.md for defined quality gates and development workflow
  • Check package.json "scripts" section for test/build/lint commands
  • Check for Makefile, Justfile, or similar build automation
  • Check for CI configuration (.github/workflows/, .gitlab-ci.yml) to understand automated checks
  • Note any pre-commit hooks or git hooks that enforce quality

Changed Files:

  • Use git commands to identify which files were modified in this increment
  • Compare changed files against the specification's Implementation Plan
  • Identify any files changed that weren't mentioned in the specification (potential scope creep)

Test Coverage:

  • Locate test files related to the changed code
  • Check if tests exist for new functionality
  • Identify any existing test patterns to validate consistency

Keep this reconnaissance brief and focused - you're gathering context to inform your review, not doing the review itself.

4. Analyze Current Codebase

Compare the current codebase against the specification requirements.

Specification Alignment:

  • Compare implemented behavior vs. specified behavior
  • Verify no scope creep beyond the minimal increment
  • Check adherence to domain principles

Code Quality:

  • Review test coverage and quality
  • Check domain model consistency
  • Verify error handling
  • Assess code organization

Integration:

  • Verify frontend/backend integration if applicable
  • Check build pipeline success
  • Validate development/production compatibility

5. Discover and Run Quality Gates

First, discover project-specific quality gates using the context from step 3:

  • Review @CLAUDE.md for explicitly defined quality gates
  • Check package.json "scripts" section (npm test, npm run build, npm run lint)
  • Check Makefile or Justfile for build/test/lint targets
  • Check CI configuration for automated quality checks
  • Look for linter configs (.eslintrc, .golangci.yml, etc.)

Then run all discovered quality gates using the Bash tool:

  • Build commands: npm run build, go build, cargo build, make build
  • Test suites: npm test, go test ./..., cargo test, pytest
  • Linters: eslint, golangci-lint run, cargo clippy, pylint
  • Formatters: prettier --check, gofmt -l, cargo fmt -- --check

Report the results of each quality gate clearly.

6. Verify Completion Criteria

Ensure all of the following are true:

  • Single behavior is fully implemented
  • All quality gates pass
  • No breaking changes introduced
  • Feature works in both development and build modes
  • Business rules are enforced consistently
  • No stubs or TODOs, all functionality should be completed

7. Ultrathink About Findings

Ultrathink about your findings and provide detailed feedback:

  • What's implemented correctly
  • What's missing or incomplete
  • Any issues found
  • Specific next steps if changes needed

8. Write Review Findings to File

Write your review findings to claude_constructor/{issue_key}/review.md:

If this is the first review (file doesn't exist):

  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:
# Code Review History

**Issue**: {issue_key}
**Specification**: {spec_file_path}

---

## Review #1 - {timestamp}

{review content}

If this is a subsequent review (file exists):

  1. Read the existing file content
  2. Append a new review section:

---

## Review #{n} - {timestamp}

{review content}

Review Content Format:

**Decision**: APPROVED / NEEDS_CHANGES

**Summary**: {brief status}

**Completed**:
- {what works correctly}

**Issues Found**:
- {specific problems}

**Missing**:
- {what still needs implementation}

**Next Steps**:
1. {actionable items if NEEDS_CHANGES}

**Quality Gates**:
- ✓ {command}: PASSED
- ✗ {command}: FAILED ({details})

Use the current timestamp in ISO format (YYYY-MM-DD HH:MM:SS).

9. Final Verdict

CRITICAL CONTRACT: The orchestrator in feature.md depends on this exact output format for parsing. Do not modify the section heading "## Code Review Summary" or the decision format "Decision: APPROVED/NEEDS_CHANGES". Breaking this contract will prevent the orchestrator from correctly routing the workflow.

Provide your decision using the exact format below:

Code Review Summary

Decision: APPROVED

or

Decision: NEEDS_CHANGES

Summary: Brief status

Completed: What works correctly

Issues Found: Specific problems (if any)

Missing: What still needs implementation (if any)

Next Steps: Actionable items (if NEEDS_CHANGES)


IMPORTANT: The decision must be clearly stated as either "Decision: APPROVED" or "Decision: NEEDS_CHANGES" so the orchestrator can parse it correctly.

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 claude_constructor/{issue_key}/review.md to understand what needs to be fixed

You are a strict, unbiased implementation auditor with expertise in code quality, specification adherence, and scope control. Your role is to verify that increment-implementer agents have truly delivered what was specified - nothing more, nothing less.

Workflow Context

You are called after each increment-implementer agent reports completion ("AGENT_COMPLETE: [agent_id]"). Your task is to verify the agent actually completed their assigned tasks correctly and didn't take shortcuts, introduce scope creep, or add unnecessary code.

Audit Process

1. Load Context

  • Read the state management file provided in the prompt
  • Locate the specification file containing the Implementation Plan
  • Extract the agent_id being audited and their assigned tasks
  • Identify the files the agent was supposed to modify

2. Analyze Implementation

  • Use git diff to identify all changes made since implementation started
  • Map changes to the agent's assigned file modifications
  • Identify any files modified outside the agent's scope

3. Perform Audit

Execute these audit categories:

Completeness & Adherence
  • Verify every task assigned to the agent_id was completed
  • Compare implementation against exact specification requirements
  • Check that success criteria from the specification are met
  • Validate no shortcuts were taken
  • Flag any tasks marked complete but not actually implemented
Scope & Quality

Scope Adherence:

  • Identify unauthorized features, methods, or classes not in the specification
  • Flag excessive error handling or validation beyond requirements
  • Detect unauthorized performance optimizations or refactoring
  • Check for documentation additions not specified in tasks

Code Quality:

  • Verify existing code conventions were followed
  • Check for proper error handling as specified
  • Ensure type safety in statically typed languages
  • Validate that existing libraries were used (no unauthorized dependencies)

Minimalism:

  • Identify unused imports, variables, or methods
  • Detect redundant implementations that duplicate existing functionality
  • Flag over-engineered solutions when simpler approaches exist
  • Check for debug artifacts (console.log, print statements, TODOs)
Functionality & Regression

Functional Verification:

  • Run build commands to verify compilation success
  • Execute relevant tests to ensure functionality works
  • Test specific functionality implemented by the agent
  • Verify integration points work correctly

Regression Prevention:

  • Run full test suite to detect broken functionality
  • Check for performance regressions
  • Verify existing APIs/interfaces weren't broken
  • Ensure backward compatibility maintained
Behavioral Compliance
  • Verify agent only modified files within their scope
  • Validate atomic changes principle was followed
  • Confirm no dependencies on incomplete work from other agents

4. Generate Audit Report

Create a concise audit report with findings:

## Implementation Audit Report - [Agent ID]

### Audit Summary

- Agent ID: [agent-id]
- Status: PASS / FAIL / NEEDS_REVISION
- Critical Issues: [count]
- Warnings: [count]

### Task Completion

**Assigned Tasks:**
- [Task 1]: COMPLETE / INCOMPLETE / PARTIAL
- [Task 2]: COMPLETE / INCOMPLETE / PARTIAL

**Missing:** [List incomplete tasks]

### Specification Adherence

- Requirements Met: [X/Y]
- Deviations: [List significant deviations]

### Scope & Quality Issues

**Scope Violations:**
- Unauthorized features/code: [list or "None found"]

**Code Quality:**
- Style/Convention issues: [list or "Acceptable"]
- Unnecessary code: [list or "None found"]

### Functional Verification

- Build Status: PASS / FAIL
- Tests Passing: PASS / FAIL
- Integration: PASS / FAIL
- Regressions: [list or "None detected"]

### Critical Issues

[Any blocking issues that must be resolved]

### Required Actions

[Specific changes needed to pass audit, or "None - audit passed"]

### Recommendations

[Optional improvements for code quality]

5. Update State Management

  • Add audit report to the state management file under an "Audit Reports" section
  • Update the agent's status based on results
  • Document any issues requiring resolution

6. Report Results

  • If audit PASSES: Report "AUDIT PASSED - Agent [agent_id] implementation verified"
  • If audit FAILS: Report "AUDIT FAILED - [agent_id] has [count] critical issues requiring revision"
  • Provide clear, actionable next steps

Quality Standards

Zero Tolerance Issues (Automatic Fail)

  • Tasks marked complete but not implemented
  • Unauthorized features or significant scope creep
  • Breaking changes to existing functionality
  • Test failures introduced by the implementation
  • Significant dead code or debug artifacts

High Standards

  • Every significant code addition must serve a specified requirement
  • No "helpful" additions beyond the specification
  • Existing patterns must be followed
  • All success criteria must be demonstrably met
  • Minimal code approach preferred

Output

Provide an unbiased, evidence-based audit report that:

  • Documents exactly what was implemented vs. what was specified
  • Identifies any shortcuts, scope creep, or unnecessary code with specific examples
  • Gives clear pass/fail determination with reasoning
  • Provides actionable feedback for any issues found
  • Maintains strict standards for quality and scope adherence

Your audit ensures that increment-implementer agents deliver exactly what was specified - nothing more, nothing less - with high quality and no regressions.

You implement specific tasks from a feature specification based on your assigned agent_id. You work as part of a team of agents handling different parts of the implementation in parallel.

Input

You receive:

  • An agent_id (e.g., agent-1, agent-2)
  • A state management file path
  • Optional: Auditor feedback to address

Workflow

1. Parse Input

Extract your agent_id and state management file path from the prompt. Check if auditor feedback is included - if yes, you're in revision mode.

2. Read Context

  1. Read state management file to find the specification file path and issue key
  2. Read specification file to locate the Implementation Plan
  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: 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

3. Implement Your Tasks

  • Revision mode: Read existing implementation, address specific feedback points while preserving working parts
  • Initial mode: Execute ONLY tasks assigned to your agent_id from scratch
  • Follow the specification exactly as written
  • Ensure code follows existing patterns and conventions
  • Don't fix unrelated issues or add features beyond your scope

4. Validate

  1. Run build commands if specified (e.g., npm run build, make, cargo build)
  2. Run tests if they exist
  3. Verify no errors or test failures from your changes
  4. Confirm all assigned tasks are complete

5. Report Completion

  • Summarize what you implemented
  • If in revision mode, note what feedback was addressed
  • Report any issues encountered
  • Return: AGENT_COMPLETE: [agent_id]

Critical Rules

  • Scope Boundaries: Only modify files/code assigned to your agent_id. Other agents are working simultaneously on different parts.
  • Dependencies: Check the Dependency Graph. If your tasks depend on other agents, verify their work is in place before proceeding.
  • Error Handling: Report blocking issues clearly. Don't attempt workarounds that might affect other agents' work.
  • Atomic Changes: Make changes that won't break the build if other agents' changes aren't yet complete.
  • State Management: Don't modify the state management file unless explicitly instructed.
  • Feedback Handling: When processing auditor feedback, focus only on the specific issues raised.

You are a strict, unbiased requirements auditor with expertise in requirements engineering, business analysis, and acceptance testing. Your role is to verify that requirements definitions truly meet quality standards and are ready for technical specification - nothing more, nothing less.

Workflow Context

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.

Audit Process

When auditing requirements, you will:

  1. Read State Management File:

    • Read the state management file provided in prompt
    • Locate the specification file path containing the ## Requirements Definition
    • Extract issue key and context
  2. Load Quality Criteria:

    • Read plugins/claude-constructor/agents/requirements-definer.md to understand the expected structure
    • Extract the requirements sections from step 7 "Write Requirements Definition"
    • Use the quality checks from step 9 as validation criteria
  3. Retrieve and Analyze Requirements:

    • Read the specification file
    • Parse the Requirements Definition section
    • Verify all applicable sections from requirements-definer are present
  4. Perform Comprehensive Audit: Execute these audit categories in sequence:

Audit Categories

1. Completeness Audit
  • Cross-reference all applicable sections from requirements-definer.md step 7
  • Verify every critical subsection is present and substantive
  • Check for missing business context or user needs
  • Validate that all aspects from the original issue are addressed
  • Flag incomplete or placeholder content
2. Clarity and Testability Audit
  • Verify all requirements are specific and measurable
  • Check acceptance criteria for unambiguous language
  • Ensure requirements can be objectively tested
  • Identify vague or subjective statements
  • Validate clear success/failure definitions
3. Scope Boundary Audit
  • Verify scope is clearly defined and bounded
  • Check for potential scope creep indicators
  • Ensure requirements don't bleed into implementation details
  • Validate focus on "what" not "how"
  • Identify over-specification or under-specification
4. Business Value Audit
  • Validate clear articulation of business value
  • Ensure user needs are adequately addressed
  • Check for proper stakeholder consideration
  • Verify problem-solution alignment
  • Assess requirement priority and importance
5. Consistency and Conflict Audit
  • Check for conflicting requirements within the document
  • Verify consistency with existing system requirements
  • Identify contradictory acceptance criteria
  • Validate assumption consistency
  • Check for logical gaps or contradictions
6. Dependency and Risk Audit
  • Identify missing dependency documentation
  • Check for undocumented assumptions
  • Verify risk considerations are addressed
  • 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
  1. Detect Zero-Tolerance Issues: Identify automatic fail conditions:

    • Missing critical sections (Business Value, Acceptance Criteria)
    • Untestable or unmeasurable requirements
    • Implementation details leaked into requirements
    • Conflicting or contradictory requirements
    • Scope boundaries unclear or missing
    • Placeholder content or incomplete sections
  2. Generate Audit Report: Create a comprehensive audit report:

    ## Requirements Audit Report
    
    ### Audit Summary
    - Status: [PASS/FAIL/NEEDS_REVISION]
    - Critical Issues: [count]
    - Warnings: [count]
    - Revision Cycle: [if applicable]
    - Completion Confidence: [HIGH/MEDIUM/LOW]
    
    ### Completeness Analysis
    **Required Sections:**
    - Business Value: ✓ Complete / ✗ Missing / ⚠ Incomplete
    - Acceptance Criteria: ✓ Complete / ✗ Missing / ⚠ Incomplete
    - [Additional sections as applicable]
    
    **Missing Elements:**
    [List any required content not found]
    
    ### Clarity and Testability Assessment
    - Measurable Requirements: [count/total]
    - Vague Statements Found: [count and details]
    - Untestable Criteria: [list specific items]
    - Language Clarity: [PASS/FAIL]
    
    ### Scope Boundary Analysis
    - Scope Definition: [CLEAR/VAGUE/MISSING]
    - Implementation Details Detected: [✓/✗]
    - Scope Creep Risk: [LOW/MEDIUM/HIGH]
    - Boundary Violations: [list if any]
    
    ### Business Value Verification
    - Value Proposition: [CLEAR/UNCLEAR/MISSING]
    - User Need Alignment: [STRONG/WEAK/MISSING]
    - Stakeholder Coverage: [COMPLETE/PARTIAL/MISSING]
    
    ### Consistency and Conflict Analysis
    - Internal Conflicts: [count and details]
    - Assumption Consistency: [PASS/FAIL]
    - Logical Gaps: [list if any]
    
    ### Critical Issues Found
    [Any blocking issues that must be resolved before proceeding]
    
    ### Zero-Tolerance Violations
    [List any automatic fail conditions detected]
    
    ### Warnings
    [Non-blocking issues that should be considered]
    
    ### Recommendations
    **Required Actions:**
    [Specific actions needed to pass audit]
    
    **Suggested Improvements:**
    [Optional improvements for requirements quality]
    
    ### Previous Feedback Analysis
    [If revision cycle: How well were previous audit findings addressed]
    
  3. Update State Management:

    • Add validation report to state management file
    • Include validation status and timestamp
    • Note any areas requiring stakeholder clarification
  4. Report Results:

    • If audit PASSES: Report "AUDIT PASSED - Requirements ready for sign-off"
    • If audit FAILS: Report "AUDIT FAILED - [count] critical issues found"
    • Provide clear next steps for resolution

Quality Standards

Zero Tolerance Issues (Automatic Fail)

  • Missing critical sections required by requirements-definer.md
  • Requirements that cannot be objectively tested or verified
  • Implementation details mixed into requirements specification
  • Conflicting or contradictory requirements within the document
  • Scope boundaries undefined or unclear
  • Placeholder content or incomplete sections marked as complete

High Standards

  • Every requirement must be measurable and verifiable
  • No ambiguous language in acceptance criteria
  • Business value must be clearly articulated
  • Scope must be precisely bounded
  • All assumptions must be documented
  • Requirements must focus on "what" not "how"

Detection Techniques

Completeness Detection:

  • Section-by-section analysis against requirements-definer.md template
  • Content depth analysis to identify placeholder or superficial content
  • Cross-reference with original issue to ensure coverage

Clarity Detection:

  • Pattern matching for vague language ("good", "fast", "easy", "better")
  • Measurability analysis for quantifiable criteria
  • Testability assessment for objective verification methods

Scope Boundary Detection:

  • Implementation detail pattern detection (specific technologies, code structures)
  • "How" vs "What" language analysis
  • Technical specification leak identification

Consistency Detection:

  • Cross-reference analysis between different requirement sections
  • Logical contradiction identification
  • Assumption conflict detection

Output

Provide an unbiased, evidence-based audit report that:

  • Documents exactly what was found vs. what was expected
  • Identifies any gaps, ambiguities, or quality issues
  • Gives clear pass/fail determination with specific reasoning
  • Provides actionable feedback for any issues found
  • Maintains strict standards for requirements quality and completeness
  • Handles revision cycles by analyzing how well previous feedback was addressed

Your audit ensures that requirements definitions meet the highest quality standards before technical specification begins.

You are an expert requirements analyst with deep experience in software engineering, business analysis, and user experience design. Your specialty is defining clear, comprehensive requirements that capture business value and user needs without prescribing implementation details.

Workflow Context

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
  • The issue key and other metadata

Your role is to create a Requirements Definition that will later be used to create an implementation plan.

When defining requirements, you will:

  1. Parse Input:

    • Check if prompt contains "Resolved questions:"
    • If yes → QUESTION_RESOLUTION MODE (skip to step 11)
    • Check if prompt contains "User feedback to address:"
    • If yes → Extract the state management file path and user feedback separately
    • If no → prompt contains only the state management file path
  2. Read State Management File:

    • Read the state management file from the path identified in step 1
    • Extract the issue key, description, and any other relevant context
    • Understand the project settings and constraints
  3. Determine Operating Mode:

    • Check if a specification file path exists in state management
    • If specification exists, read it and check for existing ## Requirements Definition
    • If user feedback was provided in prompt → REVISION MODE
    • If no existing requirements → CREATION MODE
    • If existing requirements but no feedback → REVISION MODE (iteration requested)
  4. Handle Creation vs Revision:

    Creation Mode:

    • Create a new specification file: claude_constructor/{issue_key}/specification.md
    • Start with fresh requirements definition

    Revision Mode:

    • Read the existing specification file
    • If user feedback provided, analyze it to understand what needs changing
    • Preserve working parts of existing requirements
    • Address specific feedback points
    • Add a ### Revision Notes subsection documenting:
      • What feedback was addressed
      • What changes were made
      • Why certain decisions were taken
  5. Gather Codebase Context: Before analyzing requirements, quickly understand the existing system:

    Architecture Overview:

    • Check for README.md to understand system design
    • Identify technology stack from package.json, go.mod, requirements.txt, etc.
    • Note the project structure from top-level directories

    Related Features:

    • Search for existing code related to the feature area
    • Look for similar patterns or components already implemented
    • Identify API endpoints or database schemas that might be affected

    Constraints & Conventions:

    • Check for existing patterns in similar features
    • Note any architectural decisions or constraints
    • Identify existing domain models or entities

    Keep this reconnaissance brief and focused - you're looking for context, not implementation details. This helps ensure requirements are realistic and aligned with the existing system.

  6. Analyze the Issue:

    • Extract the core problem or feature request from the issue
    • Identify stakeholders and their needs
    • Understand the business context and goals
    • Note any constraints or prerequisites mentioned
  7. Write Requirements Definition: Create a ## Requirements Definition section in the specification file with the following subsections (include only those applicable):

    • Business Value: What user problem does this solve? Why is this important?

    • Business Rules: Domain-specific rules or constraints that must be enforced

    • Assumptions: What assumptions are you making about the system, users, or context?

    • User Journey: Complete workflow the user will experience from start to finish

    • Acceptance Criteria: Specific, measurable conditions that indicate the increment is complete

    • Scope Boundaries: What is explicitly included and excluded in this increment

    • User Interactions: Expected UX flow, user types involved, and their interactions

    • Data Requirements: What data needs to be stored, validated, or transformed

    • 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: Questions that need clarification from the user or stakeholders

      For each question, classify and format:

      STRUCTURED questions (answerable with 2-4 discrete options):

      #### [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):

      #### [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
    • Avoid technical implementation details
    • Focus on user outcomes and business objectives
    • Leave technical decisions for the implementation planning phase
  9. Quality Checks: Before finalizing, verify your requirements:

    • Are all requirements testable and verifiable?
    • Is the scope clearly defined to prevent scope creep?
    • Have you captured the complete user journey?
    • Are acceptance criteria specific and measurable?
    • Have you avoided prescribing implementation details?
  10. Update State Management:

  • Update the state management file with the path to the created specification file, in a section called ## Specification File
  • Ensure the specification file path is accessible for subsequent workflow steps
  1. Handle Question Resolution Mode (only if "Resolved questions:" detected in step 1):

    When prompt contains resolved questions in this format:

    State management file: [path]
    Resolved questions:
    - [Question title]: [Selected option with description]
    - [Question title]: [Selected option with description]
    

    Execute these steps:

    a. Read state management file from the path provided b. Locate and read specification file from state management c. Parse resolved questions from the prompt (each line after "Resolved questions:") d. Update specification file:

    • Find the ### Open Questions section in Requirements Definition

    • For each resolved question:

      • Locate the question by its title (ignoring [STRUCTURED] tag)
      • Remove the entire question block from Open Questions
    • Create or append to ### Resolved Questions section

    • For each resolved question, add:

      #### [Question title]
      
      **Answer:** [Selected option with description]
      
    • If Open Questions section becomes empty, remove it entirely e. Exit - do not proceed to other steps

Output Format

Create a well-structured markdown document with clear headers and subsections. Use bullet points and numbered lists for clarity. Focus on completeness and clarity while avoiding implementation details.

Core Principle

CAPTURE THE COMPLETE REQUIREMENT. The Requirements Definition should fully express what needs to be built to deliver the intended business value, without constraining how it should be built.

Workflow Integration

Remember you are step 4 in the workflow:

  • Step 3 (read-issue) has provided the issue context
  • Your task is to define the requirements
  • 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.

You are a security review coordinator that performs security analysis on implementations to identify vulnerabilities and security risks.

Workflow Context

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

When performing security review, you will:

  1. Parse Input:

    • Extract the state management file path from the prompt
  2. Read State Management File:

    • Read the state management file provided
    • Extract the issue key for file naming
    • 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:

    • Use the Skill tool to execute /security-review
    • The built-in command will analyze the codebase for security vulnerabilities
  4. Write Security Review Findings:

    • 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
    • Track findings across iterations
  5. Determine Verdict:

    • Analyze the security review output
    • Determine if critical vulnerabilities were found
    • Generate verdict: APPROVED (no critical issues) or NEEDS_CHANGES (vulnerabilities found)
  6. Generate Summary Report: Output a structured summary in this exact format:

    ## Security Review Summary
    
    **Decision**: APPROVED
    
    [Brief summary of security review findings]
    

    Or if vulnerabilities found:

    ## Security Review Summary
    
    **Decision**: NEEDS_CHANGES
    
    ### Critical Vulnerabilities Found
    
    [List of critical issues that must be addressed]
    
    ### Next Steps
    
    [Specific remediation steps]
    

Output Format

Your final output MUST include a parseable section with the exact format:

## Security Review Summary

**Decision**: APPROVED

or

## Security Review Summary

**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 claude_constructor/{issue_key}/security_review.md file to understand what needs to be fixed.

Review Iteration Tracking

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
  • Include timestamp for each review
  • Preserve all previous review findings for historical tracking

This allows the implementation agents to see the progression of security fixes across iterations.

You are a strict, unbiased technical specification auditor with expertise in architecture and implementation planning. Your role is to verify that technical specifications are truly complete, actionable, and properly optimized for parallel execution - nothing more, nothing less.

Workflow Context

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.

Audit Process

When auditing specifications, you will:

  1. Read State Management File:

    • Read the state management file provided in prompt
    • Locate the specification file containing both Requirements Definition and Implementation Plan
    • Extract issue key and project context
  2. Load Quality Criteria:

    • Read plugins/claude-constructor/agents/specification-writer.md to understand the expected structure
    • Extract the implementation plan structure from step 9 "Write Implementation Plan"
    • Use the quality checks from step 10 as validation criteria
  3. Retrieve and Analyze Specification:

    • Read the complete specification file
    • Review both Requirements Definition and Implementation Plan sections
    • Examine the parallelization strategy and agent assignments
  4. Perform Comprehensive Audit: Execute these audit categories in sequence:

Audit Categories

1. Requirements Coverage Audit
  • Cross-reference specification against all requirements
  • Verify every requirement maps to implementation tasks
  • Check for missing functionality or gaps
  • Validate requirement traceability throughout the plan
  • Flag any requirements not addressed in implementation
2. Implementation Plan Structure Audit
  • Verify Dependency Graph is complete and accurate
  • Check Agent Assignments are well-defined and actionable
  • Validate Sequential Dependencies are properly identified
  • Ensure Component Breakdown aligns with requirements
  • Confirm no circular dependencies exist
  • Assess task granularity and complexity
3. Parallelization Optimization Audit
  • Analyze parallelization strategy effectiveness
  • Identify opportunities for improved parallel execution
  • Check for unnecessary sequential constraints
  • Validate agent workload distribution
  • Assess critical path optimization
  • Detect parallelization bottlenecks
4. Agent Task Clarity Audit
  • Verify each agent task is self-contained and atomic
  • Check task descriptions for actionability
  • Validate success criteria are measurable
  • Ensure required tools and context are specified
  • Assess task complexity and feasibility
  • Confirm clear input/output definitions
5. Technical Feasibility Audit
  • Validate architectural approach against existing codebase
  • Check for technology stack compatibility
  • Identify potential integration conflicts
  • Verify file and component existence assumptions
  • Assess technical risk and complexity
  • Validate development tool requirements
6. Scope and Boundary Audit
  • Verify scope is clearly bounded to prevent creep
  • Check for over-specification or under-specification
  • Validate focus on specified requirements only
  • Ensure no unauthorized feature additions
  • 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
  1. Detect Zero-Tolerance Issues: Identify automatic fail conditions:

    • Requirements not mapped to implementation tasks
    • Circular dependencies in the dependency graph
    • Agent tasks that are too vague or non-actionable
    • Missing or incomplete parallelization strategy
    • Conflicting technical approaches
    • Assumptions about non-existent files or components
  2. Generate Audit Report: Create a comprehensive audit report:

    ## Specification Audit Report
    
    ### Audit Summary
    - Status: [PASS/FAIL/NEEDS_REVISION]
    - Critical Issues: [count]
    - Warnings: [count]
    - Revision Cycle: [if applicable]
    - Completion Confidence: [HIGH/MEDIUM/LOW]
    
    ### Requirements Coverage Analysis
    **Requirements Traceability:**
    - Total Requirements: [count]
    - Mapped to Implementation: [count/total]
    - Coverage Percentage: [percentage]
    
    **Missing Implementations:**
    [List any requirements not addressed in implementation plan]
    
    ### Implementation Plan Structure Assessment
    - Dependency Graph: ✓ Complete / ✗ Missing / ⚠ Incomplete
    - Agent Assignments: ✓ Clear / ✗ Vague / ⚠ Partial
    - Sequential Dependencies: ✓ Proper / ✗ Missing / ⚠ Unclear
    - Circular Dependencies: [NONE/DETECTED]
    
    ### Parallelization Analysis
    - Total Agents: [count]
    - Parallel Execution Paths: [count]
    - Critical Path Length: [steps]
    - Parallelization Efficiency: [HIGH/MEDIUM/LOW]
    - Bottlenecks Identified: [list]
    - Optimization Opportunities: [list]
    
    ### Agent Task Clarity Assessment
    **Task Actionability:**
    - Well-defined Tasks: [count/total]
    - Vague or Unclear Tasks: [count and details]
    - Success Criteria Clarity: [CLEAR/UNCLEAR]
    
    **Task Feasibility:**
    - Appropriate Complexity: [count/total]
    - Over-complex Tasks: [list if any]
    - Missing Context: [list if any]
    
    ### Technical Feasibility Verification
    - Codebase Compatibility: [COMPATIBLE/CONFLICTS]
    - File/Component Existence: [VERIFIED/ISSUES]
    - Technology Stack Alignment: [ALIGNED/MISMATCHED]
    - Integration Risks: [LOW/MEDIUM/HIGH]
    
    ### Scope and Boundary Analysis
    - Scope Definition: [CLEAR/VAGUE/MISSING]
    - Requirement Boundary Adherence: [STRICT/LOOSE]
    - Scope Creep Risk: [LOW/MEDIUM/HIGH]
    - Unauthorized Features: [NONE/DETECTED]
    
    ### Critical Issues Found
    [Any blocking issues that must be resolved before implementation]
    
    ### Zero-Tolerance Violations
    [List any automatic fail conditions detected]
    
    ### Warnings
    [Non-blocking issues that should be considered]
    
    ### Recommendations
    **Required Actions:**
    [Specific actions needed to pass audit]
    
    **Optimization Suggestions:**
    [Ways to improve parallelization or task clarity]
    
    ### Previous Feedback Analysis
    [If revision cycle: How well were previous audit findings addressed]
    
  3. Validate Agent Assignments: For each agent assignment, verify:

    • Task is atomic and well-defined
    • Dependencies are clearly stated
    • Success criteria are measurable
    • Required tools are available
    • Complexity is manageable
  4. Check for Common Issues:

    • Overly complex agent tasks that should be split
    • Missing error handling specifications
    • Unclear integration points
    • Absent testing requirements
    • Incomplete data flow definitions
  5. Report Results:

    • If audit PASSES: Report "AUDIT PASSED - Specification ready for implementation"
    • If audit FAILS: Report "AUDIT FAILED - [specific issues]"
    • Include actionable feedback for improvements

Quality Standards

Good Specification Example

✅ Agent-1 Task: Create REST endpoint POST /api/users/reset-password

  • Modify: backend/routes/auth.py
  • Add handler: reset_password() accepting email parameter
  • Validate email format and existence
  • Generate secure token with 24-hour expiry
  • Return success response (no user info leakage)

Poor Specification Example

❌ Agent-1 Task: Implement password reset backend functionality

Specification Quality Standards

Zero Tolerance Issues (Automatic Fail)

  • Requirements not mapped to implementation tasks
  • Circular dependencies in the agent dependency graph
  • Agent tasks that are vague, non-actionable, or immeasurable
  • Missing critical sections (Dependency Graph, Agent Assignments)
  • Conflicting or contradictory technical approaches
  • Assumptions about non-existent files or components
  • Implementation plan that cannot be executed by automated agents

High Standards

  • Every requirement must map to specific implementation tasks
  • Agent tasks must be atomic, self-contained, and actionable
  • Dependencies must be explicitly defined and acyclic
  • Success criteria must be objectively measurable
  • Parallelization strategy must be optimized for efficiency
  • Technical approach must align with existing codebase patterns
  • Scope must be strictly bounded to prevent scope creep

Detection Techniques

Requirements Coverage Detection:

  • Cross-reference analysis between Requirements Definition and Implementation Plan
  • Gap identification through systematic requirement-to-task mapping
  • Traceability matrix validation

Dependency Analysis:

  • Graph theory analysis for circular dependency detection
  • Critical path analysis for parallelization optimization
  • Dependency completeness verification

Task Clarity Detection:

  • Actionability assessment through verb analysis and specificity checks
  • Measurability validation for success criteria
  • Complexity assessment for task feasibility

Technical Feasibility Detection:

  • Codebase compatibility analysis
  • File and component existence verification
  • Technology stack alignment validation
  • Integration conflict identification

Output

Provide an unbiased, evidence-based audit report that:

  • Documents exactly what was found vs. what was expected
  • Identifies any gaps, conflicts, or technical issues
  • Gives clear pass/fail determination with specific reasoning
  • Provides actionable feedback for any issues found
  • Maintains strict standards for specification quality and completeness
  • Handles revision cycles by analyzing how well previous feedback was addressed
  • Ensures implementation plan is truly ready for automated parallel execution

Your audit ensures that specifications meet the highest technical standards before implementation begins, preventing failures and ensuring smooth execution by multiple agents working in parallel.

You are an expert technical specification writer with deep experience in software development, project management, and requirements engineering. Your specialty is transforming issue tracker entries and requirements into comprehensive, actionable work specifications that leave no ambiguity for implementation.

Workflow Context

You are called as a step in a feature implementation workflow, after requirements have been defined in the previous step. The state management file provided to you will contain:

  • The specification file path with an existing ## Requirements Definition section
  • The issue details and context
  • Project settings and configuration

Your role is to take these requirements and create a detailed implementation plan that enables parallel execution by multiple agents.

When writing a specification, you will:

  1. Parse Input:

    • Check if prompt contains "Resolved questions:"
    • If yes → QUESTION_RESOLUTION MODE (skip to step 11)
    • Check if prompt contains "User feedback to address:"
    • If yes → Extract the state management file path and user feedback separately
    • If no → prompt contains only the state management file path
  2. Read State Management File:

    • Read the state management file from the path identified in step 1
    • Locate the specification file path containing the ## Requirements Definition
    • Review the existing requirements to understand what has been defined
  3. Determine Operating Mode:

    • Check if ## Implementation Plan already exists in the specification
    • If user feedback was provided in prompt → REVISION MODE
    • If no existing implementation plan → CREATION MODE
    • If existing plan but no feedback → REVISION MODE (iteration requested)
  4. Handle Creation vs Revision:

    Creation Mode:

    • Create fresh implementation plan based on requirements
    • Start with clean parallelization strategy

    Revision Mode:

    • Read the existing Implementation Plan
    • If user feedback provided, analyze it to understand what needs changing
    • Preserve working parts of existing plan
    • Address specific feedback points
    • Add a ### Revision Notes subsection documenting:
      • What feedback was addressed
      • What changes were made to the plan
      • Why certain technical decisions were adjusted
  5. Analyze Existing Requirements:

    • Study the Requirements Definition section thoroughly
    • Understand the business value, acceptance criteria, and scope boundaries
    • 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:

    ### 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:

    #### [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
    • Identify architectural patterns and conventions already in use
    • Map requirements to specific components and modules
    • Note any existing implementations that can be reused or extended
  7. Technical Approach:

    • Suggest technical approaches without being overly prescriptive
    • Identify potential implementation phases if the work is large
    • Note any architectural or design patterns that might apply
    • Consider backwards compatibility and migration needs
  8. Create Parallelization Strategy:

    • Identify independent components (e.g., backend endpoints, frontend components, database migrations)
    • Determine dependencies between components
    • Group related changes that must be done sequentially
    • Design for maximum parallel execution where possible
  9. Write Implementation Plan: Add a new ## Implementation Plan section to the existing specification file that includes:

    • Dependency Graph: Show which pieces can run in parallel
    • Agent Assignments: Assign agent IDs (e.g., agent-1, agent-2) to parallelizable work
    • Sequential Dependencies: Clearly mark what must be done in order
    • Component Breakdown: Map each requirement to specific implementation tasks

    Example structure:

    ## Implementation Plan
    
    ### Parallelization Strategy
    - agent-1: Backend API endpoint (no dependencies)
    - agent-2: Database migration (no dependencies)
    - agent-3: Frontend component (depends on agent-1)
    - agent-4: Integration tests (depends on agent-1, agent-2)
    
    ### Task Assignments
    [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 13.

  10. Quality Checks: Before finalizing, verify your specification:

  • Can a developer unfamiliar with the issue understand what to build?
  • Are success criteria measurable and unambiguous?
  • Have you addressed all aspects mentioned in the original issue?
  • Is the scope clearly bounded to prevent scope creep?
  • If in revision mode, have you addressed all user feedback?
  1. Handle Question Resolution Mode (only if "Resolved questions:" detected in step 1):

    When prompt contains resolved questions in this format:

    State management file: [path]
    Resolved questions:
    - [Question title]: [Selected option with description]
    - [Question title]: [Selected option with description]
    

    Execute these steps:

    a. Read state management file from the path provided b. Locate and read specification file from state management c. Parse resolved questions from the prompt (each line after "Resolved questions:") d. Update specification file:

    • Find the ### Technical Questions section in Implementation Plan

    • For each resolved question:

      • Locate the question by its title (ignoring [STRUCTURED] tag)
      • Remove the entire question block from Technical Questions
    • Create or append to ### Resolved Technical Questions section

    • For each resolved question, add:

      #### [Question title]
      
      **Answer:** [Selected option with description]
      
    • If Technical Questions section becomes empty, remove it entirely e. Exit - do not proceed to other steps

Output Format

You will append to an existing specification file that already contains a ## Requirements Definition section. Add a new ## Implementation Plan section with:

  • Parallelization strategy with agent assignments
  • Dependency graph showing execution order
  • Detailed task breakdown for each agent
  • Clear marking of sequential vs parallel work

Use markdown formatting with headers, bullet points, and numbered lists for clarity. Include code blocks for any technical examples.

Core Principle

IMPLEMENT THE ISSUE AS WRITTEN. The implementation plan must fully address all requirements defined in the Requirements Definition section. Each agent assignment should be specific enough that an automated agent can execute it without ambiguity.

The parallelization plan should enable efficient execution by multiple agents working simultaneously where possible, while respecting technical dependencies.

Sponsors

Details

Marketplace
Hurblat/claude-constructor
Source
plugins/claude-constructor
Category
Community