From 14e8d3acb05d3ea033b05a64771b2b272af6ebd8 Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Mon, 29 Sep 2025 21:36:25 +0200 Subject: [PATCH 1/5] feat: centralize workflow files in single directory --- .claude/agents/requirements-definer.md | 3 +- .claude/commands/code-review.md | 28 ++++++++++++++++++- .../commands/create-state-management-file.md | 2 +- 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/.claude/agents/requirements-definer.md b/.claude/agents/requirements-definer.md index dff986e..a3a423b 100644 --- a/.claude/agents/requirements-definer.md +++ b/.claude/agents/requirements-definer.md @@ -38,8 +38,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: `workflow_files/{issue_key}/specification.md` - Start with fresh requirements definition **Revision Mode**: diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md index c682eb8..de7f295 100644 --- a/.claude/commands/code-review.md +++ b/.claude/commands/code-review.md @@ -37,8 +37,34 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 6. Final verdict: APPROVED or NEEDS_CHANGES with clear reasons -7. Once APPROVED, add code review comment: +7. Write review findings to log file: - Extract issue key from state management file + - Check if `workflow_files/{issue_key}/review.md` exists + - If it exists, read it and count existing rounds to determine next round number + - If it doesn't exist, this is Round 1 + - Append new review round to `workflow_files/{issue_key}/review.md` with format: + ``` + ## Round {N} + **Date**: {timestamp} + **Verdict**: APPROVED or NEEDS_CHANGES + + ### Summary + [Brief status] + + ### Completed + [What works correctly] + + ### Issues Found + [Specific problems] + + ### Missing + [What still needs implementation] + + ### Next Steps + [Actionable items if NEEDS_CHANGES] + ``` + +8. Once APPROVED, add code review comment: - Use the SlashCommand tool to execute `/create-comment [issue-key] "[code review findings and verdict]"` ## Review Process diff --git a/.claude/commands/create-state-management-file.md b/.claude/commands/create-state-management-file.md index f9bba4e..db72efc 100755 --- a/.claude/commands/create-state-management-file.md +++ b/.claude/commands/create-state-management-file.md @@ -15,7 +15,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st ## Workflow Steps -1. Create a state management file called `state_management/$1.md`. +1. Create a state management file called `workflow_files/$1/state_management.md`. 2. Write the following at the top of the empty state management file: `Issue Key: {$1}` From 3f896cbef9a101ce9596d1fe79fbc050b56aea1e Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Mon, 29 Sep 2025 21:38:53 +0200 Subject: [PATCH 2/5] feat: allow hook to write to workflow_files directory --- scripts/check_path.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/scripts/check_path.py b/scripts/check_path.py index 75cc95f..1a8dcf2 100644 --- a/scripts/check_path.py +++ b/scripts/check_path.py @@ -49,6 +49,17 @@ def main(): try: common = os.path.commonpath([abs_file_path, current_dir]) if common == current_dir: + # Check if file is in workflow_files directory (allowed) + workflow_files_dir = os.path.normpath(os.path.join(current_dir, 'workflow_files')) + try: + workflow_common = os.path.commonpath([abs_file_path, workflow_files_dir]) + if workflow_common == workflow_files_dir: + # File is in workflow_files, allow it + sys.exit(0) + except ValueError: + # Not in workflow_files + pass + print("Edits are not allowed in this repository. Use external directories added with /add-dir.", file=sys.stderr) sys.exit(2) except ValueError: From aec3dd560a9b6cbd5095c644163eb848f90259a0 Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Mon, 29 Sep 2025 21:41:01 +0200 Subject: [PATCH 3/5] docs: update README to reflect workflow_files directory structure --- README.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index cd70e86..34ea5ae 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ If you use Linear or Jira for issue tracking: - **Be specific**: Whether using a feature description (`/feature Add dark mode`) or issue key (`/feature ABC-123`), provide clear requirements - **Use silent mode** for testing: Add `"silent-mode": true` to skip issue tracker updates and PR creation - **Monitor progress**: Claude Constructor will update you at each step and ask for approval at key points -- **Check the state file**: Find detailed progress in `state_management/{issue_key}.md` or `state_management/prompt-{number}.md` +- **Check workflow files**: Find detailed progress in `workflow_files/{issue_key}/` including state management, specifications, and review logs ## Core Workflow @@ -221,7 +221,7 @@ This repository is a work in progress, and there are things you might want to ch - Agent IDs assigned for parallel work with dependency management ### State Management -- Persistent tracking across all workflow steps in `state_management/{issue_key}.md` +- Persistent tracking across all workflow steps in `workflow_files/{issue_key}/state_management.md` - TODO list maintenance and resumable workflows ### Issue Tracking Integration @@ -362,13 +362,14 @@ docs/ └── git-commit.md ``` -### Generated files in your target repository: -These files are automatically created in your project during the workflow: +### Generated files in Claude Constructor repository: +These files are automatically created during the workflow: ``` -state_management/ # Tracks workflow progress -└── {issue_key}.md - -specifications/ # Technical specifications -└── {issue_key}_specification_{timestamp}.md +workflow_files/{issue_key}/ +├── state_management.md # Tracks workflow progress +├── specification.md # Requirements and implementation plan +├── review.md # Code review findings (all rounds) +└── implementation/ # Implementation logs (future) + └── {agent_id}.md ``` From c5f81fff1c843c277f81b220990257fb5e9245d2 Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Mon, 29 Sep 2025 21:47:14 +0200 Subject: [PATCH 4/5] fix: update remaining path references to workflow_files directory # Conflicts: # .claude/commands/feature.md --- .claude/commands/create-pull-request.md | 2 +- .claude/commands/feature.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/commands/create-pull-request.md b/.claude/commands/create-pull-request.md index a98068a..3e593df 100644 --- a/.claude/commands/create-pull-request.md +++ b/.claude/commands/create-pull-request.md @@ -18,7 +18,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 1. List unstaged changes using `git status` -2. Read the specification linked in the state management file ($2) and compare with unstaged changes to understand how the increment has been implemented and which unstaged changes are relevant to the increment. Ignore the specifications and state_management folders. +2. Read the specification linked in the state management file ($2) and compare with unstaged changes to understand how the increment has been implemented and which unstaged changes are relevant to the increment. Ignore the workflow_files folder. 3. Create a git commit using the guidelines in @docs/git-commit.md diff --git a/.claude/commands/feature.md b/.claude/commands/feature.md index 1a1ca15..0c0871b 100644 --- a/.claude/commands/feature.md +++ b/.claude/commands/feature.md @@ -23,9 +23,9 @@ Create a TODO list for the workflow steps, and follow it. ## Pre-Processing Before starting the workflow for user prompts, create an issue key based on $1: -- List the contents of `state_management` in the additional directories -- If there are no filenames using the format `prompt-{number}`, use issue key `prompt-1-{short-description}` -- If there is at least one filename using the format `prompt-{number}`, use issue key `prompt-{number+1}-{short-description}` +- List the contents of `workflow_files` in the additional directories +- If there are no directories using the format `prompt-{number}`, use issue key `prompt-1-{short-description}` +- If there is at least one directory using the format `prompt-{number}`, use issue key `prompt-{number+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`) ## Workflow Steps From 88fbd5b40a80c8cdca5291023f086c6e469802cf Mon Sep 17 00:00:00 2001 From: Jonas Martinsson Date: Sun, 5 Oct 2025 12:41:22 +0200 Subject: [PATCH 5/5] refactor: improve code-review command and workflow file handling --- .claude/commands/code-review.md | 22 +++++++++++-------- .claude/commands/create-pull-request.md | 2 +- .../commands/create-state-management-file.md | 6 +++-- .claude/commands/feature.md | 2 +- 4 files changed, 19 insertions(+), 13 deletions(-) diff --git a/.claude/commands/code-review.md b/.claude/commands/code-review.md index de7f295..92a2f91 100644 --- a/.claude/commands/code-review.md +++ b/.claude/commands/code-review.md @@ -1,7 +1,7 @@ --- name: code-review description: Review implementation against specification -argument-hint: [state-management-file-path] +argument-hint: [issue-key] [state-management-file-path] model: claude-sonnet-4-5 --- @@ -15,7 +15,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st ## Workflow Steps -1. Read state management file ($1) to understand the context for what you need to review +1. Read state management file ($2) to understand the context for what you need to review 2. Read the specification linked in the state management file @@ -38,11 +38,12 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 6. Final verdict: APPROVED or NEEDS_CHANGES with clear reasons 7. Write review findings to log file: - - Extract issue key from state management file - - Check if `workflow_files/{issue_key}/review.md` exists - - If it exists, read it and count existing rounds to determine next round number - - If it doesn't exist, this is Round 1 - - Append new review round to `workflow_files/{issue_key}/review.md` with format: + - Check if `workflow_files/$1/review.md` exists using: `ls workflow_files/$1/review.md 2>/dev/null || echo "not found"` + - Determine round number: + - If review.md exists: Read it and count occurrences of "## Round" to determine next round number + - If review.md doesn't exist: This is Round 1 + - Generate timestamp using: `date -u '+%Y-%m-%d %H:%M UTC'` + - Create the review entry with your findings: ``` ## Round {N} **Date**: {timestamp} @@ -61,11 +62,14 @@ You MUST follow all workflow steps below, not skipping any step and doing all st [What still needs implementation] ### Next Steps - [Actionable items if NEEDS_CHANGES] + [Actionable items if NEEDS_CHANGES, or "None - ready for PR" if APPROVED] ``` + - Write to file: + - If review.md exists: Use Edit tool to append the new round at the end + - If review.md doesn't exist: Use Write tool to create it with the round content 8. Once APPROVED, add code review comment: - - Use the SlashCommand tool to execute `/create-comment [issue-key] "[code review findings and verdict]"` + - Use the SlashCommand tool to execute `/create-comment $1 "[code review findings and verdict]"` ## Review Process diff --git a/.claude/commands/create-pull-request.md b/.claude/commands/create-pull-request.md index 3e593df..fe6cbe0 100644 --- a/.claude/commands/create-pull-request.md +++ b/.claude/commands/create-pull-request.md @@ -18,7 +18,7 @@ You MUST follow all workflow steps below, not skipping any step and doing all st 1. List unstaged changes using `git status` -2. Read the specification linked in the state management file ($2) and compare with unstaged changes to understand how the increment has been implemented and which unstaged changes are relevant to the increment. Ignore the workflow_files folder. +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. 3. Create a git commit using the guidelines in @docs/git-commit.md diff --git a/.claude/commands/create-state-management-file.md b/.claude/commands/create-state-management-file.md index db72efc..e3946b2 100755 --- a/.claude/commands/create-state-management-file.md +++ b/.claude/commands/create-state-management-file.md @@ -15,7 +15,9 @@ You MUST follow all workflow steps below, not skipping any step and doing all st ## Workflow Steps -1. Create a state management file called `workflow_files/$1/state_management.md`. +1. Create the workflow directory for this issue using `mkdir -p workflow_files/$1` -2. Write the following at the top of the empty state management file: +2. Create a state management file called `workflow_files/$1/state_management.md`. + +3. Write the following content to the newly created state management file: `Issue Key: {$1}` diff --git a/.claude/commands/feature.md b/.claude/commands/feature.md index 0c0871b..1d47337 100644 --- a/.claude/commands/feature.md +++ b/.claude/commands/feature.md @@ -44,7 +44,7 @@ Before starting the workflow for user prompts, create an issue key based on $1: 12. Implement increment - use the SlashCommand tool to execute `/implement-increment [issue-key] [state-management-file-path]` 13. Perform security review - use the SlashCommand tool to execute `/security-review`. If security vulnerabilities are found, address them and repeat the implement increment step as needed. 14. Write end-to-end tests for the increment - use the SlashCommand tool to execute `/write-end-to-end-tests [state-management-file-path]` -15. Perform code review - use the SlashCommand tool to execute `/code-review [state-management-file-path]`. If the verdict of the code review is NEEDS_CHANGES, address comments and then repeat the implement increment step. Repeat as needed. +15. Perform code review - use the SlashCommand tool to execute `/code-review [issue-key] [state-management-file-path]`. If the verdict of the code review is NEEDS_CHANGES, address comments and then repeat the implement increment step. Repeat as needed. 16. Create pull request - use the SlashCommand tool to execute `/create-pull-request [issue-key] [state-management-file-path]` 17. Review pull request - use the SlashCommand tool to execute `/review-pull-request [issue-key] [state-management-file-path]`