The Claude Code plugin for end-to-end AI development workflows. From idea to pull request: structured interview, codebase investigation, multi-agent implementation, security audit, code review, and PR creation, all automated.
Built on a Harness for long-running AI agents with strict context management, information firewalls, and a cross-session knowledge base that improves accuracy with every completed ticket.
- Claude Code CLI installed and authenticated
- GitHub CLI (
gh) — required for pull-request creation gitandjq
simple-workflow runs entirely against your local filesystem and your existing GitHub remote — no external services, no database, no separate auth.
Claude Code resolves plugin names only against marketplaces that have already been registered, so installing simple-workflow is a two-step flow: register the repository as a marketplace, then install the plugin by name from it.
# Step 1 — register aimsise/simple-workflow as a marketplace
claude plugin marketplace add aimsise/simple-workflow
# Step 2 — install the simple-workflow plugin from that marketplace
claude plugin install simple-workflow@aimsise-simple-workflowInside an active Claude Code session, the equivalent slash commands are /plugin marketplace add aimsise/simple-workflow and /plugin install simple-workflow@aimsise-simple-workflow. The aimsise-simple-workflow suffix is the name declared in .claude-plugin/marketplace.json and is what disambiguates the plugin when more than one marketplace is registered.
claude plugin install writes to your user scope (~/.claude/settings.json) by default, making the plugin available across every project on your machine. To pin the plugin to a single repository so collaborators inherit it on clone, install at project scope instead:
claude plugin install simple-workflow@aimsise-simple-workflow --scope projectProject scope writes the marketplace and plugin entry to <repo>/.claude/settings.json — commit that file to share the configuration with your team. To migrate an existing user-scope install to project scope, uninstall first so the two entries do not coexist:
claude plugin uninstall simple-workflow@aimsise-simple-workflow --scope user
claude plugin install simple-workflow@aimsise-simple-workflow --scope project--scope local is also accepted; it writes to <repo>/.claude/settings.local.json, which is gitignored, so the plugin stays installed for you on this clone but does not propagate to collaborators. Slash-command forms (/plugin install ... --scope project, /plugin uninstall ... --scope user) work identically from within an active Claude Code session.
Inside an active Claude Code session, type /brief <idea> and the plugin handles the rest end-to-end: codebase investigation, requirements interview, ticket creation, implementation, multi-agent review, and pull request.
Full argument signature: /brief <what-to-build> [mode=auto|manual] (default mode=auto).
| Mode | Command | Result |
|---|---|---|
| Full automation (default) | /brief <idea> |
Idea → PR with zero intervention; large scopes are auto-split into multiple tickets and executed in dependency order |
| Brief-assisted manual | /brief <idea> mode=manual |
Structured brief and decision policy are produced; you drive each subsequent step |
| Resume an interrupted run | /autopilot <slug> |
Pick up where a previous automated run left off using state files under .simple-workflow/backlog/ |
Three typical execution patterns:
# 1. Brief-assisted manual (type each command; repeat scout→impl→ship per ticket):
/brief <idea> mode=manual
/create-ticket
/scout
/impl
/ship # → PR
# 2. Brief manually, then hand off to autopilot for the per-ticket loop:
/brief <idea> mode=manual
/create-ticket
/autopilot <slug>
# autopilot then loops: /scout → /impl → /ship per ticket → PR
# 3. Full automation (one command):
/brief <idea> mode=auto
# brief chains: /create-ticket → /autopilot → (per ticket: /scout → /impl → /ship) → PR
Caveat — full automation works best on focused, well-scoped ideas. On overly broad or ambiguous input, the model can break output contracts, fabricate intermediate state, and continue past failures without surfacing them. Full automation has fewer human-in-the-loop checkpoints than the brief-assisted manual flow, so this kind of misbehaviour is easier to miss. For large or exploratory work, prefer
mode=manual(you inspect artifacts at each step) or split the work into smaller, focused briefs.
For phase-by-phase workflows on an existing backlog (skipping the brief), run /help inside Claude Code to discover the individual slash commands, or browse skills/ in this repository.
Tickets carry a ### Capabilities section that records which user Skills and MCP servers were available when the ticket was drafted and binds each runtime/visual acceptance criterion (live rendering, console-error count, keyboard focus/hover, WCAG contrast, network I/O, FS-state-dependent) to a concrete capability — so the downstream verifier (/impl -> ac-evaluator) picks evidence-gathering tools from the upstream-recorded mapping rather than re-deriving relevance per spawn.
simple-workflow stands on three pillars:
- Harness Engineering: structural constraints — an asymmetric information firewall between code authors and code judges (the Generator-Evaluator pattern), bounded sub-agent returns, ticket-confined artifacts, and safe-clear
[SW-CHECKPOINT]markers — enforce quality by architecture rather than by prompt instructions - Context Conservation: the context window is treated as a consumable resource — sub-agents return < 500-token summaries, artifacts live on disk, and state survives compaction
- Cross-session learning: evaluation logs are distilled into reusable patterns that future implementations inject into their prompts, so the system gets better at your project the more tickets it completes
These pillars exist because Claude Code is powerful, but its context window is finite — and fragile. Long-running agent sessions face four structural threats:
| Threat | What happens | Structural countermeasure |
|---|---|---|
| Loss | Session boundaries — compaction, exit — discard accumulated understanding | Automatic state snapshots, on-restart recovery, cross-session learning |
| Exhaustion | The window fills up, degrading instruction-following and response quality | Bounded sub-agent returns (< 500 tokens), phase-aware context release |
| Contamination | Biasing information leaks into contexts where it distorts judgment | Information firewall + ticket directory confinement (see Harness Engineering) |
| Bloat | Unbounded intermediate output crowds out critical instructions | Artifacts written to files, structured summaries returned to orchestrator |
simple-workflow addresses each threat with architectural constraints that hold regardless of model behavior — not prompt-level instructions that the model might rationalize away. For a deeper walkthrough of each pillar — Context Conservation Protocol, Harness Engineering, Knowledge Base, and Ticket Management state machine — see ARCHITECTURE.md.
The first time the plugin runs in a project, the target repository is prepared automatically: git init -b main if no repo exists (falls back to plain git init on git <2.28), an initial commit if HEAD is missing, and an idempotent append of .simple-workflow/ to .gitignore (committed as chore: add simple-workflow artifacts to .gitignore). Once .simple-workflow/.setup-done is written, simple-workflow will never touch your .gitignore again — manual deletions are permanent.
.simple-workflow/ is gitignored by default, so the ticket counter (.simple-workflow/.ticket-counter) and every other artifact stay local — each developer starts independently at T-001. To share specific paths across a team (e.g. the counter for shared numbering, or project-wide spec docs), use the surgical opt-out below. The single-line !.simple-workflow/.ticket-counter does not work because git does not descend into an ignored parent directory; the structure must always be (1) un-ignore the directory, (2) re-ignore everything by default, (3) selectively un-ignore the path(s) you want tracked.
!.simple-workflow/ # un-ignore the directory so git descends into it
.simple-workflow/* # re-ignore all contents by default
!.simple-workflow/.ticket-counter # ...except the shared ticket counter
!.simple-workflow/docs/ # ...and the docs/ directory
.simple-workflow/docs/* # re-ignore its contents
!.simple-workflow/docs/specs/ # ...except specs/
!.simple-workflow/docs/specs/** # ...including everything under specs/Anything not explicitly un-ignored stays gitignored, so research notes, plans, eval logs, and the knowledge base remain private. Concurrent ticket creation by multiple developers will produce git conflicts on a shared counter — that is the expected trade-off. simple-workflow's behavior does not depend on whether files are tracked; these patterns are purely a per-team policy decision.
Claude Code's ephemeral prompt-cache entries have a roughly 1-hour TTL. If a session sits idle past that window — for example, an overnight pause — the next turn re-warms the cache from scratch and can rewrite hundreds of thousands of cache_creation tokens in a single turn.
Recommendation: if a simple-workflow session has been idle for more than ~1 hour, exit and start a fresh session. Phase-terminating workflows emit a [SW-CHECKPOINT] block precisely so that /clear or session exit is safe, and the plugin reconstructs the in-progress phase from phase-state.yaml on the next session.
If an automated run ends with a partial status before reaching the context-window cap, the model likely self-aborted before Claude Code's auto-Compaction had a chance to fire. Run /autopilot <slug> in a fresh session to pick up where it left off — state files in .simple-workflow/backlog/ provide the resume point.
Long-running /autopilot pipelines automatically run /compact at the ticket boundary so the conversation context does not fill up between tickets. /compact is injected via terminal-multiplexer keystroke from hooks/pre-next-scout-auto-compact.sh (primary) and hooks/post-ship-state-auto-compact.sh (safety net). After compaction hooks/session-start.sh re-injects /autopilot <slug> and the resume contract picks up the next ticket from autopilot-state.yaml.
- Default: ON inside an autopilot run, OFF outside.
- Kill switch: set
SW_AUTO_COMPACT_ON_SHIP_MODE=offin your environment to disable (preserves the pre-v7 behaviour).SW_AUTO_COMPACT_ON_SHIP_MODE=metric-onlylogs the intent without injecting.
hooks/lib/inject-keys.sh types /compact and the post-compact /autopilot <slug> back into the originating terminal surface — not whichever surface the user happens to focus when the hook fires. Support depends on what remote-control interface the host terminal exposes:
| Terminal | Supported | Notes |
|---|---|---|
| tmux, GNU screen, WezTerm | Yes | No extra setup |
| kitty | Yes | Requires allow_remote_control yes in kitty.conf |
| iTerm2 | Single iTerm window only | Needs macOS Automation permission (osascript → iTerm). Multiple iTerm windows are unsolvable via AppleScript — refocus the originating window before each ticket boundary, or use tmux |
| Apple Terminal, Warp, Ghostty, Windows | No | Focus-leak risk (Apple Terminal) or no pane-targeted send-text CLI (others) |
Recommendation: run claude inside tmux for any unattended autopilot run. It is the only supported backend whose injection is provably correct under arbitrary focus changes during a multi-hour run, and it requires no OS configuration.
When injection cannot fire, the hook surfaces a one-line diagnostic via inject_keys_failure_hint as additionalContext in the next turn, and the autopilot continues — /compact is best-effort and never blocks /scout / Edit / Write.
- Designed for use with Claude Code CLI. IDE extensions (VS Code, JetBrains) may have limited support for hooks and plugin features.
- Pull-request creation requires GitHub CLI (
gh) with authentication. Other Git hosting services are not supported. - Ticket management uses the local filesystem (
.simple-workflow/backlog/). There is no sync with external issue trackers (Jira, Linear, etc.). - Sub-agents consume API tokens independently. Large tickets (L/XL) using Opus may result in higher API costs.
- Built-in test/lint detection covers JS, Python, Rust, Go, JVM (Gradle/Maven/sbt), .NET, Ruby, Elixir, Swift, Flutter/Dart, PHP, and Make. For other ecosystems, wrap your test/lint commands in a Makefile (
make test/make lint) or the evaluator falls back to static code analysis only. - Some recovery paths require interactive mode; running in
claude -por CI may stop with an explanatory message rather than complete the recovery.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.