Agent workflow

Three portable skills. One FR per clean session. No plugin, hooks, dependencies, automatic reviewers, or prescribed model. Works with Claude Code and Pi, including local models such as Qwen. Skills guide the agent; they do not enforce execution.

Install in a project

Requires Python 3 for setup only:

python3 /path/to/agents-workflow-template/setup.py /path/to/project

Setup installs the Pi /fr adapter in .pi/extensions/fr/, copies the same three skills into .claude/skills/ and .pi/skills/, creates workflow/README.md, and adds a short pointer to AGENTS.md and CLAUDE.md. Existing files are preserved; differing installed skills/adapters cause setup to stop before writing anything. Copies make projects self-contained on other machines. No global settings are changed. Run setup again safely; updates are explicit, not automatic.

Then ask your agent to fill in workflow/README.md with the project's existing verification commands and confirm them with you. Reuse existing scripts; don't create a second command registry. Never run placeholder commands.

Restart/reload your agent to discover the skills. In Claude Code invoke /workflow-plan, /workflow-implement, /workflow-review; in Pi use /skill:workflow-plan, /skill:workflow-implement, /skill:workflow-review. You can also ask the agent to read the corresponding SKILL.md directly.

The whole workflow

1. Plan together. Agree on scope. Write one feature document with small, observable FRs and focused implementation briefs. Human approval precedes coding.
2. Implement one FR in a clean session. Run relevant checks, update its status and leave a short handoff. Stop. No full suite per FR.
3. Start another clean session for the next FR. Repeat until the feature is done.
4. Review in a separate clean session. Inspect the actual diff and requirements; reuse valid test evidence. Fix substantive findings in implementation sessions.
5. Handoff. Run full verification once on the settled feature, record the result and remaining manual checks. Human commits. Recheck only what later fixes invalidate.

Clean sessions, including local Qwen

In Pi, use /fr <feature-path> to automate clean-session handoffs. For manual handoffs use /new; in Claude Code use /clear or start a new conversation. Confirm the selected model after resetting. Do not carry over a conversation summary: the FR brief and project files are the handoff.

Start each implementation session with just:

Use workflow-implement. Implement FR-2 in workflow/001-file-upload.md.

Keep each FR small enough for one session. Include its goal, acceptance criteria, relevant paths, dependencies, and settled decisions in its brief. Read those files on demand rather than loading all PRDs, logs, or the entire repository. If a brief cannot be understood without a huge history, improve or split it before coding. This reduces context pressure; it is not a guarantee that every model can solve every task. Stop for a decision rather than guessing or looping indefinitely.

Pi auto-chain (installed by default)

Normal setup includes the adapter. To install only the skills:

python3 /path/to/agents-workflow-template/setup.py /path/to/project --no-pi-fr

The exclusion flag skips installation; it does not delete an existing adapter.

Reload Pi, then run /fr workflow/001-file-upload.md (or /fr path/to/feature/ for a directory containing requirements.md). Confirm once. It implements open FRs in document order, each in a clean session preserving model and thinking level. It stops when done or blocked; review and commits remain manual. No project names, stack commands, test policy or PRD-index discovery live in the adapter.

Provide one authoritative status table with FR ID first and a Status column:

| ID | Requirement | Status |
|---|---|---|
| FR-1 | Upload a file | Ready |
| FR-2 | List uploaded files | Ready |

Or use headings like ## FR-1: Upload a file — Ready. Supported statuses are Ready, Accepted (ready alias), Blocked, Implemented, Verified and Dropped. Also supported: todo/in-progress (ready), done (implemented), dropped (excluded). The Status column may be followed by Notes; without a header, status must be last. A table takes precedence over detail headings. Keep FRs in dependency order; the agent still checks prerequisites. Malformed/unknown statuses stop the chain. Select an approved feature explicitly; it never moves to another feature.

Use Esc to interrupt work; do not manually mark an interrupted FR Implemented. Reloading, resuming or restarting Pi does not auto-resume the chain. Run /fr again to explicitly resume from the recorded statuses. Do not run two chains on the same feature. The adapter checks statuses, not test truth: the skill/agent must report failed or incomplete required verification and must not call the completion tool.

The adapter is TypeScript loaded by Pi, not a standalone runtime. Claude Code continues using the same skills with manual clean-session handoffs. Adapter checks: node --test tests/pi-fr.test.mjs (requires installed Pi).

Existing projects

Existing PRDs can stay where they are; reference them instead of migrating them. Disable the old PRD plugin for the project before using these skills. Remove its project-specific overrides/patches and old FR launcher only after checking what other tooling still uses them. Keep valuable tests and scoped verification scripts. Setup does not disable installed plugins or delete project files for you.

This repository replaces the old marketplace in source only. It does not uninstall cached plugins. Do not run old /prd:build alongside this workflow.

Keep it small

• Three skills, plain Markdown, no runtime required.
• Project commands and conventions stay in the project.
• Risk-based tests; no mandatory TDD, coverage quota, or test per FR.
• One independent review, no automatic subagent fan-out or vendor pairing.
• One compact verification record; no process diaries or duplicate reports.
• No hidden shell hooks, success caches, opt-out hierarchy, or automatic commits.

Validate setup changes with python3 tests/test_setup.py. Test skills by using them on a small real feature in each harness; prompt quality cannot be proven by a shell smoke test.