agent-workflow-system

agent-workflow-system.md

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:

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

.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:

.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:

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:

~/.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:

.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:

---
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-name>/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:

Plan
 ↓
Spec
 ↓
Requirement
 ↓
Task
 ↓
Implementation

Every artifact must reference its parent.

---

Plan → Spec

Every specification must reference a plan.

Example:

Parent Plan:
PLAN-001

Source:
docs/plans/2026-06-10-user-notifications/SUMMARY.md

---

Spec → Requirement

Every requirement must have a unique identifier.

Example:

REQ-001
Users shall receive email notifications.

REQ-002
Users shall manage notification preferences.

---

Requirement → Task

Every task must reference a requirement.

Example:

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:

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:

docs/plans/YYYY-MM-DD-feature-name/

Generate:

SUMMARY.md
phase-01.md
phase-02.md
...

---

Workflow

Load Context

Read:

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:

plans
specs
tasks

Identify:

• Gaps
• Ambiguity
• Missing requirements
• Missing tasks
• Contradictions

---

Transparency Requirement

The Refiner must never silently assume missing information.

Instead it must:

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:

Plan → Spec
Spec → Requirement
Requirement → Task

---

Generate Findings

Example:

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:

docs/specs/
tasks-implementation.md

---

Stop

Wait for approval.

No architecture. No implementation.

---

architect

Purpose

Design the technical solution.

---

Responsibilities

Create:

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:

Requirements
+
Architecture
+
Tasks

into code.

---

Workflow

Read

• Plans
• Specs
• Architecture
• Tasks

---

Implement

Follow tasks exactly.

---

Verification

Run:

• Tests
• Linting
• Build

---

Produce Report

Create:

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

review-report.md

Containing:

• Critical issues
• Major issues
• Minor issues
• Suggestions

---

Decision

APPROVED

or

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:

P0
P1
P2
P3

---

Generate Refinement Plan

Create:

docs/plans/YYYY-MM-DD-refinement/

---

Produce

• Lessons learned
• New requirements
• Updated backlog
• Next iteration plan

---

Handoff

Return to:

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.