Skip to content

Centralized workflow directory #27

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

Closed
Hurblat wants to merge 5 commits into from
Closed

Centralized workflow directory #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
14e8d3a
feat: centralize workflow files in single directory
Hurblat Sep 29, 2025
3f896cb
feat: allow hook to write to workflow_files directory
Hurblat Sep 29, 2025
aec3dd5
docs: update README to reflect workflow_files directory structure
Hurblat Sep 29, 2025
c5f81ff
fix: update remaining path references to workflow_files directory
Hurblat Sep 29, 2025
88fbd5b
refactor: improve code-review command and workflow file handling
Hurblat Oct 5, 2025
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
3 changes: 1 addition & 2 deletions .claude/agents/requirements-definer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**:
Expand Down
40 changes: 35 additions & 5 deletions .claude/commands/code-review.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---

Expand All @@ -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

Expand All @@ -37,9 +37,39 @@ 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:
- Extract issue key from state management file
- Use the SlashCommand tool to execute `/create-comment [issue-key] "[code review findings and verdict]"`
7. Write review findings to log file:
- 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}
**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, 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 $1 "[code review findings and verdict]"`

## Review Process

Expand Down
2 changes: 1 addition & 1 deletion .claude/commands/create-pull-request.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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

Expand Down
6 changes: 4 additions & 2 deletions .claude/commands/create-state-management-file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,9 @@ You MUST follow all workflow steps below, not skipping any step and doing all st

## Workflow Steps

1. Create a state management file called `state_management/$1.md`.
1. Create the workflow directory for this issue using `mkdir -p 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}`
8 changes: 4 additions & 4 deletions .claude/commands/feature.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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]`

Expand Down
19 changes: 10 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
```
11 changes: 11 additions & 0 deletions scripts/check_path.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down