Skip to content

feat: centralize workflow files in claude_constructor directory #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Hurblat merged 8 commits into from
Jan 20, 2026
Merged

feat: centralize workflow files in claude_constructor directory #34

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
65bf80b
feat: centralize workflow files under claude_constructor/{issue_key}/
Hurblat Jan 20, 2026
57395d8
feat(workflow): add resume capability for interrupted workflows
Hurblat Jan 20, 2026
8bcfa5b
feat(workflow): add interactive question resolution via AskUserQuestion
Hurblat Jan 20, 2026
3a07bd2
refactor: migrate SlashCommand to Skill tool
Hurblat Jan 20, 2026
df28c88
docs(workflow): clarify agent status format in implement-increment
Hurblat Jan 20, 2026
117c816
docs(workflow): clarify ambiguous instructions
Hurblat Jan 20, 2026
f2a5780
docs(workflow): fix step numbering and placeholder consistency
Hurblat Jan 20, 2026
be5086d
docs(workflow): improve command specifications from review feedback
Hurblat Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"name": "claude-constructor",
"source": "./plugins/claude-constructor",
"description": "A workflow automation system that helps Claude Code implement features systematically with built-in planning, validation, and review steps",
"version": "1.1.0"
"version": "1.2.0"
}
]
}
29 changes: 15 additions & 14 deletions .claude/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,21 @@
{
"permissions": {
"allow": [
"SlashCommand(/create-state-management-file:*)",
"SlashCommand(/read-settings:*)",
"SlashCommand(/requirements-sign-off:*)",
"SlashCommand(/specification-sign-off:*)",
"SlashCommand(/git-checkout:*)",
"SlashCommand(/implement-increment:*)",
"SlashCommand(/issue:read-issue:*)",
"SlashCommand(/issue:get-issue:*)",
"SlashCommand(/issue:update-issue:*)",
"SlashCommand(/issue:create-comment:*)",
"SlashCommand(/write-end-to-end-tests:*)",
"SlashCommand(/security-review:*)",
"SlashCommand(/create-pull-request:*)",
"SlashCommand(/review-pull-request:*)"
"Skill(/create-state-management-file:*)",
"Skill(/read-settings:*)",
"Skill(/requirements-sign-off:*)",
"Skill(/specification-sign-off:*)",
"Skill(/git-checkout:*)",
"Skill(/implement-increment:*)",
"Skill(/issue:read-issue:*)",
"Skill(/issue:get-issue:*)",
"Skill(/issue:update-issue:*)",
"Skill(/issue:create-comment:*)",
"Skill(/write-end-to-end-tests:*)",
"Skill(/security-review:*)",
"Skill(/create-pull-request:*)",
"Skill(/review-pull-request:*)",
"Skill(/implementation-summary:*)"
]
},
"env": {
Expand Down
3 changes: 2 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
.claude/settings.local.json
.claude/settings.claude-constructor.local.json
__pycache__
node_modules/
node_modules/
claude_constructor/
12 changes: 6 additions & 6 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,19 +37,19 @@ plugins/claude-constructor/

**State Management:**

- Workflow progress tracked in `state_management/{issue_key}.md` files (created in projects that use the plugin)
- Workflow progress tracked in `claude_constructor/{issue_key}/state_management.md`
- Each workflow step updates the state file with its outputs
- Enables resumable workflows and cross-step communication

**Specifications:**

- Created in `specifications/{issue_key}_specification_{timestamp}.md` (in target projects)
- Created in `claude_constructor/{issue_key}/specification.md`
- Contains Requirements Definition and Implementation Plan sections
- Used throughout implementation and review phases

**Code Reviews:**

- Review history tracked in `code_reviews/{issue_key}.md` files (created in target projects)
- Review history tracked in `claude_constructor/{issue_key}/review.md`
- Each review iteration appends findings, verdict, and quality gate results
- Implementation team reads latest review when addressing feedback

Expand All @@ -59,9 +59,9 @@ The `/feature` command (in `commands/feature.md`) orchestrates a sequential work

1. **Planning phase**: Read config → Create state file → Read settings → Read issue → Define requirements → Validate requirements → Requirements sign-off → Write specification → Validate specification → Specification sign-off
2. **Implementation phase**: Checkout branch → Implement → Security review → Write E2E tests
3. **Review phase**: Code review → Create PR → Review PR
3. **Review phase**: Code review → Create PR → Review PR → Generate summary

Each step is a separate command. The orchestrator blocks until user sign-off at the **requirements sign-off** and **specification sign-off** steps.
Each step is a separate command. The orchestrator blocks until user sign-off at the **requirements sign-off** and **specification sign-off** steps. The workflow concludes with a comprehensive implementation summary.

### Issue Tracking Integration

Expand Down Expand Up @@ -119,5 +119,5 @@ When modifying workflow commands or agents:

1. Use `--silent=true` argument to skip external API calls (e.g., `/feature ABC-123 --silent=true`)
2. Test with `/feature prompt-test-description` to avoid needing real issues
3. Check `state_management/`, `specifications/`, and `code_reviews/` outputs in target project
3. Check `claude_constructor/{issue_key}/` outputs (state_management.md, specification.md, review.md, security_review.md, implementation_summary.md)
4. Verify all workflow steps complete in sequence without hanging or skipping steps
43 changes: 34 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,31 @@ That's it. Claude Constructor will guide you through planning → approval → i
| `/write-end-to-end-tests` | Implementation |
| `/create-pull-request` | Review |
| `/review-pull-request` | Review |
| `/implementation-summary` | Review |

## Resuming Workflows

If your session ends mid-workflow, simply run `/feature` with the same issue key. Claude Constructor will detect existing progress and offer to resume:

```text
Progress for ABC-123:
- [x] Requirements defined + approved
- [x] Specification written + approved
- [ ] Implementation ← Resume point

Existing workflow found for ABC-123. Resume from 'Implementation'?
> Resume (Recommended)
> Start Fresh
```

**What gets preserved:**

- Approved requirements and specifications
- Completed implementation agents (parallel work)
- Security and code review history
- Git branch and PR state

**Start Fresh:** Archives the existing state to `claude_constructor/{issue_key}-archived-{timestamp}/` and begins a new workflow.

## Agents

Expand Down Expand Up @@ -119,16 +144,16 @@ Create `.claude/settings.claude-constructor.local.json`:
Claude Constructor creates these files in your target project:

```text
state_management/
└── {issue_key}.md # Workflow progress and context

specifications/
└── {issue_key}_spec_{ts}.md # Requirements + implementation plan

code_reviews/
└── {issue_key}.md # Review history across iterations
claude_constructor/{issue_key}/
├── state_management.md # Workflow progress, context, and resume markers
├── specification.md # Requirements + implementation plan
├── review.md # Code review findings (all rounds)
├── security_review.md # Security review findings
└── implementation_summary.md # Final summary of what was built
```

The `state_management.md` file tracks workflow progress including approval states, git branch, and PR URL—enabling seamless workflow resume across sessions.

## Team Setup

Add to your project's `.claude/settings.json`:
Expand Down Expand Up @@ -178,7 +203,7 @@ Changes to command/agent files are immediately available. Changes to `plugin.jso

- **Be specific:** Clear requirements upfront = better results
- **Use silent mode:** `--silent=true` skips external APIs for testing
- **Check state files:** `state_management/{issue_key}.md` shows detailed progress
- **Check state files:** `claude_constructor/{issue_key}/state_management.md` shows detailed progress
- **Stay engaged:** Monitor implementation and provide feedback at checkpoints

## Plugin Structure
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "claude-constructor",
"version": "1.0.0",
"version": "1.2.0",
"description": "A workflow automation plugin for Claude Code",
"private": true,
"scripts": {
Expand Down
2 changes: 1 addition & 1 deletion plugins/claude-constructor/.claude-plugin/plugin.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "claude-constructor",
"description": "A workflow automation system that helps Claude Code implement features systematically with built-in planning, validation, and review steps",
"version": "1.1.0",
"version": "1.2.0",
"author": {
"name": "Jonas Martinsson & Anders Hassis",
"url": "https://github.com/Hurblat/claude-constructor/graphs/contributors"
Expand Down
10 changes: 5 additions & 5 deletions plugins/claude-constructor/agents/code-reviewer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Extract the state management file path from the prompt.
2. Extract the specification file path from the state management file
3. Read the specification to understand requirements
4. Extract the issue key from the state management file (needed for reporting and file naming)
5. Determine code-review file path: `code_reviews/{issue_key}.md`
5. Determine code-review file path: `claude_constructor/{issue_key}/review.md`
6. If code-review file exists, read it to count existing reviews (for review iteration number)

### 3. Gather Review Context
Expand Down Expand Up @@ -118,12 +118,12 @@ Ultrathink about your findings and provide detailed feedback:

### 8. Write Review Findings to File

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

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

1. Create the `code_reviews/` directory if it doesn't exist
2. Create the file with header metadata:
1. Create the file with header metadata (directory should already exist from state management creation):
2. Use Write tool to create the file with header metadata:

```markdown
# Code Review History
Expand Down Expand Up @@ -209,4 +209,4 @@ or
**Workflow continuation**:

- If APPROVED: The orchestrator will create an issue comment with your findings and proceed to create a pull request
- If NEEDS_CHANGES: The orchestrator will loop back to the implementation step. The implementation team will read `code_reviews/{issue_key}.md` to understand what needs to be fixed
- If NEEDS_CHANGES: The orchestrator will loop back to the implementation step. The implementation team will read `claude_constructor/{issue_key}/review.md` to understand what needs to be fixed
2 changes: 1 addition & 1 deletion plugins/claude-constructor/agents/increment-implementer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ Extract your agent_id and state management file path from the prompt. Check if a
3. Find the Task Assignments section
4. Identify your specific tasks based on your agent_id
5. Check for code review feedback:
- Determine code-review file path: `code_reviews/{issue_key}.md`
- Determine code-review file path: `claude_constructor/{issue_key}/review.md`
- If file exists: Read the latest review to understand what needs fixing
- If review feedback is relevant to your tasks, prioritize addressing those issues

Expand Down
10 changes: 9 additions & 1 deletion plugins/claude-constructor/agents/requirements-definer-auditor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ You are a strict, unbiased requirements auditor with expertise in requirements e

## Workflow Context

You are called as a audit checkpoint after requirements have been defined (step 5) and before sign-off (step 7). Your task is to ensure the requirements meet quality standards before proceeding to technical specification.
You are called as an audit checkpoint after requirements have been defined (step 4) and before sign-off (step 6). Your task is to ensure the requirements meet quality standards before proceeding to technical specification.

You may also be called to audit requirements that have been revised based on previous feedback, in which case you should analyze both the original issues and how well the revisions addressed them.

Expand Down Expand Up @@ -85,6 +85,14 @@ When auditing requirements, you will:
- Validate integration point clarity
- Assess technical constraint documentation

#### 7. Open Questions Format Audit

- Verify all questions are tagged as `[STRUCTURED]` or `[OPEN-ENDED]`
- Check STRUCTURED questions have exactly 2-4 options
- Validate options are mutually exclusive and clearly distinct
- Ensure questions are specific and answerable
- Verify option descriptions provide enough context for decision-making

5. **Detect Zero-Tolerance Issues**:
Identify automatic fail conditions:
- Missing critical sections (Business Value, Acceptance Criteria)
Expand Down
42 changes: 35 additions & 7 deletions plugins/claude-constructor/agents/requirements-definer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ You are an expert requirements analyst with deep experience in software engineer

## Workflow Context

You are called as step 5 in a feature implementation workflow. The state management file provided to you will contain:
You are called as step 4 in a feature implementation workflow. The state management file provided to you will contain:

- Issue details and context from the issue tracker
- Project settings and configuration
Expand Down Expand Up @@ -39,8 +39,7 @@ When defining requirements, you will:
4. **Handle Creation vs Revision**:

**Creation Mode**:
- Create a new specification file: `specifications/{issue_key}_specification_{timestamp}.md`
- Use the current timestamp to ensure uniqueness
- Create a new specification file: `claude_constructor/{issue_key}/specification.md`
- Start with fresh requirements definition

**Revision Mode**:
Expand Down Expand Up @@ -93,7 +92,36 @@ When defining requirements, you will:
- **Integration Points**: How this integrates with existing systems or components
- **Error Handling**: How errors and edge cases should be handled gracefully
- **Performance Expectations**: Any specific performance or scalability requirements
- **Open Questions**: Anything that needs clarification from the user or stakeholders
- **Open Questions**: Questions that need clarification from the user or stakeholders

For each question, classify and format:

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

```markdown
#### [STRUCTURED] Question title

Full question text?

- **Option A**: First option description
- **Option B**: Second option description
- **Option C**: Third option (if needed)
- **Option D**: Fourth option (if needed)
```

**OPEN-ENDED questions** (require detailed explanation):

```markdown
#### [OPEN-ENDED] Question title

Full question text requiring free-form response?
```

Guidelines:

- Prefer STRUCTURED when possible (faster resolution)
- STRUCTURED questions must have exactly 2-4 options
- Options should be mutually exclusive

8. **Focus on "What" not "How"**:
- Define what needs to be accomplished, not how to implement it
Expand Down Expand Up @@ -124,11 +152,11 @@ Create a well-structured markdown document with clear headers and subsections. U

## Workflow Integration

Remember you are step 5 in the workflow:
Remember you are step 4 in the workflow:

- Step 4 (read-issue) has provided the issue context
- Step 3 (read-issue) has provided the issue context
- Your task is to define the requirements
- Step 6 (requirements-sign-off) will review your work
- Step 5 (audit) and step 6 (requirements-sign-off) will review your work
- Step 7 (write-specification) will use your requirements to create an implementation plan

The requirements you define will be the foundation for all subsequent implementation work, so they must be complete, clear, and focused on business value.
14 changes: 7 additions & 7 deletions plugins/claude-constructor/agents/security-reviewer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
---
name: security-reviewer
description: Performs security analysis by calling the built-in /security-review command to identify vulnerabilities and security risks in the implementation
tools: SlashCommand, Read, Write
tools: Skill, Read, Write
color: red
---

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 12) to ensure the code is secure before proceeding to end-to-end tests (step 14). Your task is to run the built-in `/security-review` command and persist the findings for tracking.
You are called after implementation (step 11) to ensure the code is secure before proceeding to end-to-end tests (step 13). Your task is to run the built-in `/security-review` command and persist the findings for tracking.

## Security Review Process

Expand All @@ -21,15 +21,15 @@ When performing security review, you will:
2. **Read State Management File**:
- Read the state management file provided
- Extract the issue key for file naming
- Determine security review file path: `security_reviews/{issue_key}.md`
- Determine security review file path: `claude_constructor/{issue_key}/security_review.md`
- If file exists, read it to count existing review iterations

3. **Execute Security Review**:
- Use the SlashCommand tool to execute `/security-review`
- Use the Skill tool to execute `/security-review`
- The built-in command will analyze the codebase for security vulnerabilities

4. **Write Security Review Findings**:
- Create or append to `security_reviews/{issue_key}.md`
- Create or append to `claude_constructor/{issue_key}/security_review.md`
- Include review iteration number (e.g., "Security Review #1", "Security Review #2")
- Include timestamp
- Write the complete output from `/security-review`
Expand Down Expand Up @@ -85,11 +85,11 @@ or
**Decision**: NEEDS_CHANGES
```

The orchestrator will parse this decision to determine workflow routing. If APPROVED, the workflow proceeds. If NEEDS_CHANGES, the workflow loops back to implementation where agents will read the `security_reviews/{issue_key}.md` file to understand what needs to be fixed.
The orchestrator will parse this decision to determine workflow routing. If APPROVED, the workflow proceeds. If NEEDS_CHANGES, the workflow loops back to implementation where agents will read the `claude_constructor/{issue_key}/security_review.md` file to understand what needs to be fixed.

## Review Iteration Tracking

When writing to `security_reviews/{issue_key}.md`:
When writing to `claude_constructor/{issue_key}/security_review.md`:

- First review: Create the file with "# Security Review #1"
- Subsequent reviews: Append "# Security Review #N" sections
Expand Down
10 changes: 9 additions & 1 deletion plugins/claude-constructor/agents/specification-writer-auditor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ You are a strict, unbiased technical specification auditor with expertise in arc

## Workflow Context

You are called as a audit checkpoint after specification writing (step 8) and before sign-off (step 10). Your task is to ensure the implementation plan is technically sound and ready for execution by automated agents.
You are called as an audit checkpoint after specification writing (step 7) and before sign-off (step 9). Your task is to ensure the implementation plan is technically sound and ready for execution by automated agents.

You may also be called to audit specifications that have been revised based on previous feedback, in which case you should analyze both the original issues and how well the revisions addressed them.

Expand Down Expand Up @@ -90,6 +90,14 @@ When auditing specifications, you will:
- Confirm implementation stays within requirement boundaries
- Identify potential scope expansion risks

#### 7. Technical Questions Format Audit

- Verify all questions are tagged as `[STRUCTURED]` or `[OPEN-ENDED]`
- Check STRUCTURED questions have exactly 2-4 options
- Validate options represent valid technical alternatives
- Ensure questions relate to implementation decisions, not requirements
- Verify option descriptions provide enough context for decision-making

5. **Detect Zero-Tolerance Issues**:
Identify automatic fail conditions:
- Requirements not mapped to implementation tasks
Expand Down
Loading