Claude Code has unified commands into skills with the user-invocable
frontmatter field. This migration:
- Converts 20 commands to skills with user-invocable: true
- Consolidates docs into single writing-capabilities.md
- Rewrites capability-writing skill for unified model
- Updates CLAUDE.md, Makefile, and other references
- Removes commands/ directory
Skills now have two types:
- user-invocable: true - workflows users trigger with /name
- user-invocable: false - background knowledge auto-loaded
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Resolves issue #86 by having the spawn-issues orchestrator create worktrees
upfront and pass the worktree paths to agents, instead of having agents
create their own worktrees in sibling directories outside the sandbox.
Changes:
- spawn-issues orchestrator creates all worktrees before spawning agents
- issue-worker, pr-fixer, code-reviewer accept optional WORKTREE_PATH
- When WORKTREE_PATH is provided, agents work directly in that directory
- Backward compatible: agents still support creating their own worktrees
if WORKTREE_PATH is not provided
- Orchestrator handles all worktree cleanup after agents complete
- Eliminates permission denied errors from agents trying to access
sibling worktree directories
This ensures agents operate within their sandbox while still being able to
work with isolated git worktrees for parallel implementation.
Closes#86
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Set explicit model preferences to optimize for speed vs capability:
- haiku: 11 commands, 2 agents (issue-worker, pr-fixer), 10 skills
Fast execution for straightforward tasks
- sonnet: 4 commands (groom, improve, plan-issues, review-pr),
1 agent (code-reviewer)
Better judgment for analysis and review tasks
- opus: 2 commands (arch-refine-issue, arch-review-repo),
1 agent (software-architect)
Deep reasoning for architectural analysis
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add linter detection logic that checks for common linter config files
(ESLint, Ruff, Flake8, Pylint, golangci-lint, Clippy, RuboCop)
- Add instructions to run linter on changed files only
- Add "Lint Issues" section to review output format
- Clearly distinguish lint issues from logic/security issues
- Document that lint issues alone should not block PRs
Closes#25
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Introduces a new command that guides users through creating capabilities
for the architecture repository. The command analyzes user descriptions,
recommends appropriate component combinations (skill, command, agent),
gathers necessary information, generates files from templates, and presents
them for approval before creation.
Closes#75
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add model: sonnet to issue-worker agent (balanced for implementation)
- Add model: sonnet to pr-fixer agent (balanced for feedback iteration)
- Add model: haiku to /dashboard command (read-only display)
- Add model: haiku to /roadmap command (read-only categorization)
- Document rationale for each model selection in frontmatter comments
Closes#72
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Creates a lighter-weight PR creation flow for when you're already on a
branch with commits. Features:
- Auto-generates title from branch name or commits
- Auto-generates description summarizing changes
- Links to related issue if branch name contains issue number
- Triggers code-reviewer agent after PR creation
Closes#19
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add new section to display recent workflow runs from tea actions runs
- Show status indicators: [SUCCESS], [FAILURE], [RUNNING], [PENDING]
- Highlight failed runs with bold formatting for visibility
- Gracefully handle repos without CI configured
- Include example output format for clarity
Closes#20
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The planning process previously jumped directly from understanding a feature
to breaking it down into issues. This led to proposing issues without first
understanding the user's actual workflow and where the gaps are.
Added a discovery phase that requires walking through:
- Who is the specific user
- What is their goal
- Step-by-step workflow to reach the goal
- What exists today
- Where the workflow breaks or has gaps
- What's the MVP
Issues are now derived from workflow gaps rather than guessing.
Closes#29
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add streamlined commit workflow that analyzes staged changes and
generates conventional commit messages (feat:, fix:, etc.) with
user approval before committing.
Closes#18
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Creates a skill that teaches how to design and create capabilities
(skill + command + agent combinations) for the architecture repository.
Includes:
- Component templates for skills, commands, and agents
- Decision tree and matrix for when to use each component
- Model selection guidance (haiku/sonnet/opus)
- Naming conventions and anti-patterns to avoid
- References to detailed documentation in docs/
- Checklists for creating each component type
Closes#74
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Architecture Beliefs section to manifesto with outcome-focused beliefs:
auditability, business language in code, independent evolution, explicit over implicit
- Create software-architecture.md as human-readable documentation
- Enhance software-architecture skill with beliefs→patterns mapping (DDD, Event
Sourcing, event-driven communication) and auto-trigger description
- Update work-issue command to reference skill and check project architecture
- Update issue-worker agent with software-architecture skill
- Add Architecture section template to vision-management skill
The skill is now auto-triggered when implementing, reviewing, or planning
architectural work. Project-level architecture choices go in vision.md.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The code reviewer prompt was minimal and didn't specify worktree setup,
causing parallel reviewers to interfere with each other by checking out
different branches in the same directory.
Changes:
- Add worktree setup/cleanup to code reviewer prompt (like issue-worker/fixer)
- Add branch tracking to issue state
- Add note about passing branch name to reviewers
- Expand reviewer prompt with full review process
This ensures each reviewer works in isolation at:
../<repo>-review-<pr-number>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Creates a new command that refines issues with architectural perspective
by spawning the software-architect agent to analyze the codebase before
proposing implementation guidance. The command:
- Fetches issue details and spawns software-architect agent
- Analyzes existing patterns and affected components
- Identifies architectural concerns and dependencies
- Proposes refined description with technical notes
- Allows user to apply, edit, or skip the refinement
Closes#59
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add software architecture review as a standard part of PR review process:
- Reference software-architecture skill for patterns and checklists
- Spawn software-architect agent for architectural analysis
- Add checks for pattern consistency, dependency direction, breaking changes,
module boundaries, and error handling
- Structure review output with separate Code Review and Architecture Review
sections
Closes#60
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Creates a new command that spawns the software-architect agent to perform
comprehensive architecture audits. The command analyzes directory structure,
package organization, patterns, anti-patterns, dependencies, and test coverage,
then presents prioritized recommendations with a health score.
Closes#58
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace polling loop with task-notification based orchestration.
Background tasks send notifications when complete - no need to poll.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Create the software-architect agent that performs deep architectural
analysis on codebases. The agent:
- References software-architecture skill for patterns and checklists
- Supports three analysis types: repo-audit, issue-refine, pr-review
- Analyzes codebase structure and patterns
- Applies architectural review checklists from the skill
- Identifies anti-patterns (god packages, circular deps, etc.)
- Generates prioritized recommendations (P0-P3)
- Returns structured ARCHITECT_ANALYSIS_RESULT for calling commands
Closes#57
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Creates the foundational skill that encodes software architecture
best practices, review checklists, and patterns for Go and generic
architecture guidance.
Closes#56
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Each issue flows independently through: implement → review → fix → review
- Don't wait for all workers before starting reviews
- Print status update as each step completes
- Poll loop checks all tasks, advances each issue independently
- State machine: implementing → reviewing → fixing → approved/failed
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
spawn-issues now orchestrates the full workflow:
- Phase 1: Spawn issue-workers in parallel, wait for completion
- Phase 2: Review loop - spawn code-reviewer, if needs work spawn pr-fixer
- Phase 3: Report final status
issue-worker simplified:
- Removed Task tool and review loop
- Just implements, creates PR, cleans up
- Returns structured result for orchestrator to parse
Benefits:
- Better visibility into progress
- Reuses pr-fixer agent
- Clean separation of concerns
- Orchestrator controls review cycle
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The inline prompt in spawn-issues.md was missing the review loop
that was added to issue-worker/agent.md. Now includes:
- Step 7: Spawn code-reviewer synchronously, fix and re-review if needed
- Step 9: Concise final summary output
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Task tool to spawn code-reviewer synchronously
- Add review loop: fix issues and re-review until approved (max 3 iterations)
- Add final summary format for cleaner output to spawning process
- Reviewer works in same worktree, cleanup only after review completes
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Background agents need skills specified in frontmatter rather than
using @ syntax which may not expand for Task-spawned agents.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New command that spawns background agents to work on multiple
issues simultaneously, each in an isolated git worktree.
- commands/spawn-issues.md: Entry point, parses args, spawns agents
- agents/issue-worker/agent.md: Autonomous agent that implements
a single issue (worktree setup, implement, PR, cleanup)
Worktrees are automatically cleaned up after PR creation.
Branch remains on remote for follow-up work if needed.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds guidance to prefer vertical slices (user-visible value) over
horizontal slices (technical layers) when planning and writing issues.
roadmap-planning skill:
- New "Vertical vs Horizontal Slices" section
- Demo test: "Can a user demo/test this independently?"
- Good vs bad examples table
- When horizontal slices are acceptable
issue-writing skill:
- New "Vertical Slices" section
- Demo test guidance
- Good vs bad issue titles table
- User-focused issue framing examples
Closes#31
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Skills are knowledge modules referenced by commands, not
directly invoked by users. Added user-invocable: false to:
- backlog-grooming (used by /groom)
- claude-md-writing (used by /update-claude-md)
- code-review (used by /review-pr)
- issue-writing (used by /create-issue)
- roadmap-planning (used by /plan-issues)
- vision-management (used by /vision, /manifesto)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updates or creates CLAUDE.md with:
- Organization context section (links to manifesto, repos.md, vision)
- Current project structure from filesystem scan
- Architecture patterns inferred or asked
Preserves existing custom content, shows diff before writing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Create claude-md-writing skill with best practices for CLAUDE.md files
- Create repos.md registry of all repos with status (Active/Planned/Splitting)
- Update /create-repo to include organization context section
- Update repo-conventions to reference new skill
Each repo's CLAUDE.md now links to manifesto, repos.md, and vision.md
so Claude always understands the bigger picture.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Skill documents standard repo structure, naming conventions,
open vs proprietary guidance, and CI/CD patterns.
Command scaffolds new repos with vision.md, CLAUDE.md, Makefile,
CI workflow, and .gitignore - all linked to the architecture repo.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Software should run well on modest hardware. ARM64-native where possible.
Bloated software is a sign of poor engineering.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Product repos find the manifesto at ../architecture/manifesto.md.
This allows the architecture repo to be a sibling of product repos.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rebuild vision.md to trace personas, jobs, and principles back to manifesto
- Improve /vision command with inheritance guidance and templates
- Update vision-management skill with explicit inheritance rules and formats
Product visions now explicitly extend (not duplicate) organization manifesto.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Shift from developer-centric personas (solo dev, small team) to the actual
mission: empowering domain experts to create software without coding.
- Who We Serve: Domain experts, Agencies, Organizations (small → enterprise)
- Added "Empowering Domain Experts" beliefs section
- Integrated "build in public" into Who We Are
- Updated non-goals to align with new focus
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated all internal references for the rename:
- CLAUDE.md: New purpose statement, updated structure, added manifesto info
- README.md: Updated title, clone URL, folder structure
- commands/retro.md: Changed flowmade-one/ai to flowmade-one/architecture
The actual Gitea rename should be done after merging this PR.
Closes#44🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Restructured skill to clearly distinguish:
- Manifesto: Organization-level (architecture repo)
- Vision: Product-level (product repos)
Key additions:
- Architecture table showing all three levels with commands
- Manifesto section with structure, when to update, creation steps
- Vision section clarified as product-level extending manifesto
- Relationship diagram showing inheritance model
- Example of persona inheritance (org → product)
- Continuous improvement loop including retro → encoding flow
- Quick reference table for common questions
Closes#43🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changed the retro flow to:
1. Retro (any repo) → Issue (architecture repo)
2. Later: Encode issue into learning file + skill/command/agent
Key changes:
- Retro now only creates issues, not learning files
- Learning files are created when the issue is worked on
- All issues go to architecture repo regardless of source repo
- Added "When the Issue is Worked On" section for encoding guidance
- Clearer separation between capturing insights and encoding them
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Clarifies /vision is for product-level vision, distinct from /manifesto
which handles organization-level vision.
Changes:
- Added architecture table showing org vs product vs goals levels
- Process now checks for manifesto first for org context
- Output format includes Organization Context section
- Guidelines clarify when to use /manifesto vs /vision
- Product personas/jobs extend (not duplicate) org-level ones
Closes#41🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds new command to view and manage the organization-level manifesto.
Distinct from /vision which handles product-level vision.
Features:
- Guides manifesto creation if none exists
- Displays formatted summary of existing manifesto
- References vision-management skill
- Clear output format for all sections
Closes#40🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds learnings folder for capturing insights from retros and daily work.
Learnings serve as historical record, governance reference, and encoding
source for skills/commands/agents.
README includes:
- Purpose explanation (historical + governance + encoding)
- Learning template with all sections
- Encoding process and destination guide
- Periodic review guidance
- Naming conventions
Closes#39🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Defines the foundational organization-level vision:
- Who We Are: Small, focused AI-native builders
- Personas: Solo developer, Small team, Agency/Consultancy
- Jobs to Be Done: Ship fast, maintain quality, stay in flow
- Beliefs: AI-augmented development, quality without ceremony, sustainable pace
- Guiding Principles: Encode don't document, small teams big leverage, etc.
- Non-Goals: Enterprise compliance, every platform, replacing judgment
Closes#38🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The vision system now guides defining WHO we build for and WHAT they're
trying to achieve before jumping into goals and issues.
Updated vision-management skill:
- New vision.md structure with Personas and Jobs to Be Done sections
- Guidance for defining good personas (specific, characterized, limited)
- Guidance for jobs to be done (outcome-focused, in their voice, pain-aware)
- Milestones now tied to personas and jobs with structured descriptions
- Issue alignment checks persona/job fit before milestone fit
Updated vision command:
- Guides through persona and JTBD definition when creating vision
- Output format shows personas and jobs prominently
- Guidelines emphasize traceability to personas
Updated plan-issues command:
- Identifies persona and job before breaking down work
- Plan presentation includes For/Job/Supports context
- Flags misalignment with persona/job, not just goals
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
