--- name: agent-workflow-system description: Generate a reusable agent-driven project workflow as filesystem-based Agent Skills. Use when bootstrapping planning, refinement, architecture, implementation, review, and iteration skills for personal software projects. --- # Agent Workflow System Specification ## Objective Create a reusable agent-driven workflow system for personal software projects. The system enforces a structured lifecycle: ```text Idea ↓ plan-writer ↓ plan-refiner ↓ architect ↓ implementer ↓ reviewer ↓ refine-again ``` The workflow is specification-first and requires traceability between plans, specifications, and implementation tasks. --- # Canonical Setup Sequence Project setup must follow this order: 1. Set up the project structure. 2. Ask which agent runtime the user is setting up: Claude Code, Codex, both, or another runtime. 3. Clone and install selected third-party skills into the runtime-appropriate skill directory. 4. Create the project's own workflow skills as valid `SKILL.md` files in the runtime-appropriate project skill directory. 5. Verify the project's own skills can discover and use appropriate external skills for specialized tasks. Do not skip cross-skill verification when external skills are installed. --- # Goals * Prevent implementation before requirements are clear. * Ensure every implementation task traces back to a requirement. * Ensure every requirement traces back to a plan. * Enable continuous refinement and iteration. * Allow agents to discover and use more specialized skills when available. * Standardize project organization across repositories. * Support solo-founder workflows without unnecessary process overhead. --- # Non-Goals * Replace project management tools. * Replace source control workflows. * Replace CI/CD systems. * Enforce specific programming languages or frameworks. --- # Directory Structure ```text .agents/ └── skills/ ├── init-project/ │ └── SKILL.md ├── plan-writer/ │ └── SKILL.md ├── plan-refiner/ │ └── SKILL.md ├── architect/ │ └── SKILL.md ├── implementer/ │ └── SKILL.md ├── reviewer/ │ └── SKILL.md └── refine-again/ └── SKILL.md docs/ ├── plans/ ├── specs/ └── tasks-implementation.md ``` Runtime-specific project skill directories: ```text .claude/skills/ # Claude Code project skills .agents/skills/ # Codex/project agent skills ``` --- # Runtime Target Selection During setup, ask the user which agent runtime they are using before installing or generating skills. Supported choices: * Claude Code * Codex * Both Claude Code and Codex * Other Use the runtime choice to decide where to install third-party skills and where to generate the project's own workflow skills. | Runtime | Third-party skill target | Project workflow skill target | | --- | --- | --- | | Claude Code | `~/.claude/skills/` | `.claude/skills/` | | Codex | `~/.codex/skills/` | `.agents/skills/` | | Both | `~/.claude/skills/` and `~/.codex/skills/` | `.claude/skills/` and `.agents/skills/` | | Other | Ask for the user-level skill directory | Ask for the project-level skill directory | If the user selects `Other`, confirm that the runtime supports directory-based skills with `SKILL.md` frontmatter before generating or copying skills. If it uses a different format, ask for the expected format and adapt only after approval. --- # External Skill Sources Project setup may install skills from trusted external repositories. Default external source: ```sh git clone https://github.com/alirezarezvani/claude-skills.git ``` Install only selected skill folders from an external source. Do not bulk-install every folder by default. Target locations: ```text ~/.claude/skills/ # Claude Code ~/.codex/skills/ # Codex custom path # Other runtimes, user-provided ``` ## External Skill Install Rules Before copying an external skill: * Use the runtime target selected during setup. * Ask for approval before cloning remote repositories or writing to home-directory skill folders. * Clone the repository into a temporary or vendor directory outside the generated skill target. * Inspect the selected skill folder before installation. * Copy only folders that contain a valid `SKILL.md`. * Verify each copied `SKILL.md` follows the Skill File Format section. * Preserve the original folder name unless it violates skill naming rules. * Do not overwrite an existing installed skill without approval. * Treat external skills as executable third-party code and surface any scripts or unusual file access patterns. Installed external skills are reusable capabilities, not project requirements. They must not change the generated plans, specs, or implementation tasks unless a later workflow step explicitly uses them. --- # Cross-Skill Usage Generated workflow skills must be able to use skills from other sources when those skills are installed and appropriate for the task. Relevant skill sources include: ```text .agents/skills/ # Project workflow skills .claude/skills/ # Claude Code project skills ~/.claude/skills/ # Claude Code user skills ~/.codex/skills/ # Codex user skills custom paths # Other runtime skill directories ``` ## Skill Selection Rules Before a generated skill starts substantive work: 1. Identify the task type and required expertise. 2. Check available skill metadata from project and installed external skill sources. 3. Prefer the most specific skill that directly matches the task. 4. Use external skills for specialized work such as research, UI design, security review, framework-specific implementation, document generation, or domain analysis. 5. Use generated workflow skills for lifecycle control: planning, refining, architecture, implementation, review, and iteration. 6. Combine skills only when their responsibilities are complementary. 7. Do not use a skill whose scope conflicts with the active workflow boundary. 8. State which skills are being used and why. ## Cross-Skill Handoff Rules When a generated workflow skill uses another skill: * Pass only the context needed for the subtask. * Preserve the current workflow boundary. * Validate the other skill's output before integrating it. * Do not let an external skill overwrite requirements, plans, or tasks without explicit workflow approval. * Record any assumptions, risks, or unresolved questions returned by the other skill. --- # Skill File Format Every generated workflow skill must be a directory containing a `SKILL.md` file. Each `SKILL.md` must start with YAML frontmatter: ```yaml --- name: skill-name description: Brief description of what this skill does and when to use it. --- ``` ## Required Fields `name`: * Use lowercase letters, numbers, and hyphens only. * Keep it under 64 characters. * Do not use XML tags. * Do not use reserved words such as `anthropic` or `claude`. `description`: * Keep it non-empty. * Keep it under 1024 characters. * Explain both what the skill does and when to use it. * Do not use XML tags. ## Body Format After frontmatter, each generated skill must include: * `# Skill Name` * `## Purpose` * `## When to Use` * `## Responsibilities` * `## Skill Discovery` * `## Workflow` * `## Output` * `## Boundaries` Generated skills may include extra sections only when they improve execution clarity. ## Generation Rule When this system generates or regenerates any workflow skill, it must write valid Agent Skill files, not plain prompt files. Do not generate `.agents/skills/*.md` files directly; generate `.agents/skills//SKILL.md`. Each generated workflow skill must include the Cross-Skill Usage rules in its `## Skill Discovery` section so it can use appropriate skills from project, Claude Code, or Codex skill sources. --- # Traceability Rules The system follows strict traceability: ```text Plan ↓ Spec ↓ Requirement ↓ Task ↓ Implementation ``` Every artifact must reference its parent. --- ## Plan → Spec Every specification must reference a plan. Example: ```md Parent Plan: PLAN-001 Source: docs/plans/2026-06-10-user-notifications/SUMMARY.md ``` --- ## Spec → Requirement Every requirement must have a unique identifier. Example: ```md REQ-001 Users shall receive email notifications. REQ-002 Users shall manage notification preferences. ``` --- ## Requirement → Task Every task must reference a requirement. Example: ```md TASK-001 Requirement: REQ-001 Description: Implement notification service. ``` --- ## Orphan Rule The Refiner must flag: * Tasks without requirements. * Requirements without tasks. * Specs without plans. * Plans without specs. --- # init-project ## Purpose Bootstrap the workflow system. --- ## Responsibilities Create: ```text docs/plans/ docs/specs/ docs/tasks-implementation.md ``` Ask the user whether they are setting up Claude Code, Codex, both, or another runtime. Create the runtime-appropriate project skill directory from the Runtime Target Selection section. Optionally install selected external skills from trusted sources into the runtime-appropriate user skill directory. Generate starter skill directories with `SKILL.md` files that follow the Skill File Format section and include `## Skill Discovery`. Verify generated skills can use appropriate external skills without violating workflow boundaries. Never overwrite existing files without approval. --- ## Workflow ### Step 1 Check existing project structure. ### Step 2 Create missing project directories. ### Step 3 Ask which agent runtime the user is using: Claude Code, Codex, both, or another runtime. If another runtime: 1. Ask for the user-level third-party skill directory. 2. Ask for the project-level workflow skill directory. 3. Confirm whether the runtime supports `SKILL.md` files with YAML frontmatter. ### Step 4 Ask whether to install external skills. If yes: 1. Confirm source repository, defaulting to `https://github.com/alirezarezvani/claude-skills.git`. 2. Confirm the runtime-derived target skill directory. 3. Ask for approval to clone the source repository and write selected skills to the target skill directory. 4. Clone the source into a temporary or vendor directory. 5. List available skill folders. 6. Ask which selected skills to install. 7. Copy selected valid skill folders into the chosen target skill directory. 8. Report skipped folders and validation issues. ### Step 5 Generate the project's own workflow skill directories in the runtime-appropriate project skill directory, using `SKILL.md` files that follow the Skill File Format section. ### Step 6 Verify each generated workflow skill includes `## Skill Discovery` and can use appropriate installed external skills for specialized subtasks. ### Step 7 Generate tasks file. ### Step 8 Output setup report. --- ## Success Criteria * All folders exist. * All skill files exist. * Runtime choice is recorded in the setup report. * Any requested external skills are installed in the selected runtime skill directory. * Generated workflow skills are installed in the selected runtime project skill directory. * Any skipped external skills are reported with reasons. * Generated workflow skills include `## Skill Discovery`. * Generated workflow skills can use appropriate external skills without crossing their workflow boundaries. * No existing files overwritten. --- # plan-writer ## Purpose Convert an idea into an implementation plan. --- ## Responsibilities Create: ```text docs/plans/YYYY-MM-DD-feature-name/ ``` Generate: ```text SUMMARY.md phase-01.md phase-02.md ... ``` --- ## Workflow ### Load Context Read: ```text docs/plans/ docs/specs/ tasks-implementation.md ``` --- ### Gather Requirements Determine: * Goal * Audience * Scope * Constraints * Success metrics --- ### Create Plan Include: * Overview * Goals * Non-goals * Risks * Dependencies --- ### Create Phases Each phase contains: * Objective * Complexity * Tasks * Verification * Expected Output --- ### Stop No implementation. --- # plan-refiner ## Purpose Act as a requirements auditor. --- ## Responsibilities Analyze: ```text plans specs tasks ``` Identify: * Gaps * Ambiguity * Missing requirements * Missing tasks * Contradictions --- ## Transparency Requirement The Refiner must never silently assume missing information. Instead it must: ```text State assumption Explain risk Ask user for clarification ``` --- ## Workflow ### Read Plans Load all relevant plans. --- ### Read Specs Load all related specifications. --- ### Read Tasks Load implementation tasks. --- ### Cross-Reference Validate: ```text Plan → Spec Spec → Requirement Requirement → Task ``` --- ### Generate Findings Example: ```text Missing Requirement Coverage REQ-007 exists. No implementation task found. ``` --- ### Ask Clarifying Questions Questions must focus on: * Business logic * Edge cases * Permissions * Failure handling * Constraints --- ### Update Artifacts Update: ```text docs/specs/ tasks-implementation.md ``` --- ### Stop Wait for approval. No architecture. No implementation. --- # architect ## Purpose Design the technical solution. --- ## Responsibilities Create: ```text docs/specs/architecture.md ``` --- ## Workflow ### Read * Plans * Specs * Refined requirements --- ### Design Produce: * Components * Services * APIs * Data model * Integrations --- ### Define Risks Document: * Scaling risks * Security risks * Performance risks --- ### Output Architecture specification. --- ### Stop No coding. --- # implementer ## Purpose Implement approved work. --- ## Responsibilities Translate: ```text Requirements + Architecture + Tasks ``` into code. --- ## Workflow ### Read * Plans * Specs * Architecture * Tasks --- ### Implement Follow tasks exactly. --- ### Verification Run: * Tests * Linting * Build --- ### Produce Report Create: ```text implementation-report.md ``` Containing: * Files changed * Tests added * Verification results * Known limitations --- # reviewer ## Purpose Validate implementation quality. --- ## Responsibilities Review: * Requirements coverage * Code quality * Security * Performance * Testing --- ## Workflow ### Read * Specs * Architecture * Implementation report --- ### Analyze Check: * Requirement coverage * Missing functionality * Security concerns * Technical debt --- ### Produce Report ```text review-report.md ``` Containing: * Critical issues * Major issues * Minor issues * Suggestions --- ### Decision ```text APPROVED ``` or ```text CHANGES REQUESTED ``` --- # refine-again ## Purpose Turn lessons learned into the next iteration. --- ## Responsibilities Analyze: * Review findings * Bugs * User feedback * Metrics --- ## Workflow ### Collect Findings Gather: * Production issues * Feedback * Test failures --- ### Prioritize Classify: ```text P0 P1 P2 P3 ``` --- ### Generate Refinement Plan Create: ```text docs/plans/YYYY-MM-DD-refinement/ ``` --- ### Produce * Lessons learned * New requirements * Updated backlog * Next iteration plan --- ### Handoff Return to: ```text plan-refiner ``` for the next cycle. --- # Universal Skill Rules All skills must follow these rules. --- ## Skill Discovery Before executing: 1. Identify the task type and required expertise. 2. Check whether a more specialized skill exists in project skills or installed external skills. 3. Prefer the most specialized skill available. 4. Use existing agent capabilities when appropriate. 5. Consider installed external skills in `~/.claude/skills/` or `~/.codex/skills/` when available. 6. Use the appropriate external skill for specialized subtasks, then integrate the result within the active workflow boundary. 7. Do not duplicate existing functionality. --- ## Transparency Every skill must: * State assumptions. * Explain decisions. * Highlight uncertainty. * Surface risks. Never silently infer critical requirements. --- ## Ownership Boundaries ### plan-writer May: * Create plans Must not: * Design architecture * Write code --- ### plan-refiner May: * Audit requirements Must not: * Design architecture * Write code --- ### architect May: * Design systems Must not: * Write production code --- ### implementer May: * Write code Must not: * Invent requirements --- ### reviewer May: * Critique implementation Must not: * Rewrite requirements --- ### refine-again May: * Create future iterations Must not: * Modify implementation directly --- # Definition of Done The workflow is complete when: * Every plan has a linked spec. * Every spec has linked requirements. * Every requirement has linked tasks. * Every task has been implemented. * Reviewer approves implementation. * Refinement backlog is documented. * Traceability is preserved end-to-end.