Smithery is now a part of Arcade.dev! Read more in our announcement here
AI-augmented software engineering workflow based on Addy Osmani's methodology...
AI-augmented software engineering workflow that maximizes LLM effectiveness through structured planning, clear context, strategic delegation, and human accountability.
This skill is invoked primarily in Cowork sessions. In Cowork, its output is always an artifact — a plan, a spec, a delegation prompt, or a review. It is not an execution surface for code.
| Surface | This skill produces | Execution happens in |
|---|---|---|
| Cowork (primary) | Plan, spec, delegation prompt, review, handoff doc | Claude Code CLI (via terminal) or Ruflo (swarm/scale) |
| Claude Code CLI | Can load for reference; informs pair-mode coaching | In place (the CLI itself writes/edits files) |
When an agent running in Cowork reads an example that says "implement the feature" or "run the tests," the correct action is to produce a delegation prompt and hand off to Claude Code, not to attempt implementation in-session. Cowork's Desktop Commander MCP can invoke Claude Code remotely, but the skill's own advice is about the handoff artifact, not in-session edits.
This skill synthesizes Addy Osmani's LLM coding workflow, Anthropic's agentic coding research, Harper Reed's spec-driven pipeline, and patterns from 30+ real-world projects. It supports two collaboration modes — interactive pair programming and autonomous delegation — and provides a systematic approach to AI-assisted development that prevents wasted cycles while enabling increasingly autonomous execution.
Core philosophy. The human engineer is the accountable owner; the AI is a capable collaborator whose autonomy scales with the quality of the prompt. Well-scoped delegation with clear acceptance criteria is not "blind trust" — it is a higher-leverage operating mode.
Two Collaboration Modes:
| Mode | When | How | Review |
|---|---|---|---|
| Pair Mode (Conductor) | Ambiguous problems, design decisions, learning new domains | Interactive back-and-forth; AI as thought partner | Line-by-line as you go |
| Delegation Mode (Orchestrator) | Well-scoped tasks with clear acceptance criteria | Structured prompt → autonomous execution → human review | Deliverable review against spec |
From a Cowork session, this skill's three most common outputs are:
For actual file edits, builds, or test runs, hand off to Claude Code via Desktop Commander (cd <repo> && claude) or via a Task agent. See iac/github-playbook for the handoff conventions.
Before you plan, make sure you're planning the right thing. Most people arrive with a solution in their head ("build me a dashboard") when the real need is something different ("I need three numbers emailed to me every Monday"). One prompt closes the gap:
"I'm about to start this project. Interview me until you have 95% confidence about what I actually want, not what I think I should want."
This flips the dynamic. Instead of pitching an idea and hoping the AI reads your mind, the AI asks the questions that surface assumptions you did not know you were making. It separates the what from the why before a single line of planning gets done.
How to use it: start every new project or feature with this prompt (or something close). Answer honestly, including "I don't know yet" — the gaps are where the value is. Let the AI play it back ("So what you actually need is ___. Is that right?"). Only after confirmation should you move to Principle 1.
This is especially valuable in Delegation Mode — if the spec is wrong, everything downstream is wrong. Five minutes of interviewing saves five hours of rework.
Never start implementation without a plan. Use AI to rapidly create detailed specifications covering functional requirements, edge cases, technical constraints, preferred patterns, and success criteria. This is "waterfall in 15 minutes" — rapid structured planning that prevents wasted cycles. For the full spec format, see iac/spec-driven-development.
Decompose large asks into bounded, independently verifiable units — not because models can't handle scope, but because review, rollback, and commits operate at the unit level. A unit is the largest slice you can check against acceptance criteria in one pass; each gets its own commit.
Supply related files and patterns, API documentation, technical constraints, preferred approaches, and known anti-patterns. Context quality still dominates output quality at any model tier — a precise context package outperforms a vague prompt to a stronger model.
In Cowork, context is provided via Read, MCP tool calls (Drive, Confluence, Notion), and explicit reference to repo files. In Claude Code, use /context add or @file references.
Match model to task — deep reasoning and architecture, fast iteration, multimodal input — and use current pro-tier versions; specific model rankings shift faster than this document. When output is wrong, fix the spec and context before reaching for a different model: that is where the leverage is.
Modern AI coding agents (Claude Code, Cursor, Copilot Workspace) read files, run tests, fix bugs, open PRs, and execute multi-step tasks autonomously. The question is not whether to delegate, but how much supervision to apply.
Guardrails scale with scope, not with distrust:
| Delegation scope | Guardrails |
|---|---|
| Single file fix | Commit diff review |
| Feature implementation | Spec review + test pass + code review |
| Multi-service change | Spec review + integration tests + manual QA |
| Infrastructure / security | Never fully delegate; pair mode only |
You own the output. Review depth scales with delegation scope, not with suspicion.
iac/code-review-and-quality for the five-axis framework and sizing thresholds.The operating model is "delegate, review, own" — not "distrust and micromanage." A well-scoped prompt with clear acceptance criteria earns a deliverable-level review, not a line-by-line audit.
Treat commits as save points in a game. Commit after each small task completes successfully. Benefits: easy rollback if AI suggestions introduce bugs, clear progression in history, safe experimentation. Commit messages follow your team's convention (Conventional Commits, short imperative, etc.) — for Eric's setup, see iac/github-playbook.
Create rules files to guide AI outputs toward team idioms. For Claude Code, CLAUDE.md at repo root is loaded automatically; for other agents, the equivalent is .cursorrules, GEMINI.md, or the system prompt. Capture: code style, preferred patterns, anti-patterns, testing conventions, and anything else that would otherwise be repeated in every prompt.
Robust CI/CD enhances AI productivity. Automated feedback loops help refine outputs: linter errors, type errors, and failing tests are exactly the kind of signal agents can act on autonomously. Wire up the pipeline and feed failures back to the agent — most will iterate to green without further guidance.
Using AI doesn't dull skills — it amplifies existing expertise. LLMs reward best practices. Review every piece of AI-generated code to understand why it made specific choices. Debug AI mistakes yourself first before asking for a fix. Keep notes on effective prompts. The insights compound.
When a task is well-scoped with clear acceptance criteria, delegation mode lets you hand off implementation to an AI agent and review the deliverable rather than supervising each step.
Before delegating, verify:
## Task
[One-sentence description of what to build/fix/refactor]
## Context
- Project: [repo name, relevant paths]
- Stack: [language, framework, key libraries]
- Related files: [list specific files the agent should read]
## Acceptance Criteria
1. [Specific, testable criterion]
2. [Specific, testable criterion]
3. [Specific, testable criterion]
## Constraints
- Follow existing patterns in [file/directory]
- Do not modify [protected areas]
- All tests must pass before marking complete
## Out of Scope
- [Explicitly list what NOT to do]
For complex projects, delegation spans multiple tiers. Each tier is optimized for a different scope of work, and the spec is the handoff document between them.
| Tier | Surface | Role | Example |
|---|---|---|---|
| Design | Cowork | Architecture, spec writing, review, decision capture | "Design the auth system; write spec.md" |
| Build | Claude Code CLI | Autonomous multi-file implementation | "Implement the auth API per spec.md; make tests pass" |
| Scale | Ruflo | Parallel multi-agent execution | "Run 4 agents: API, tests, docs, migration" |
Cowork is where the thinking happens. Claude Code is where the code gets written. Ruflo is where work parallelizes across agents. Always write the spec in Cowork before handing off to the next tier.
Delegation fails. Plan for it. When a delegated task returns a broken deliverable:
These are the three patterns that actually fit the Cowork surface. Each produces an artifact Eric can carry forward — to Claude Code, to a PR description, to a tracker — not an in-session code edit.
Input: An underspecified ask ("add SSO to LogiQ").
Cowork action: Run the Principle 0 interview. Produce a written plan with clarifying questions resolved, acceptance criteria, and a file/path map. Write it to the project's SESSION.md or a new spec.md.
Handoff: Eric opens Claude Code in the repo and says "implement spec.md." The plan is the contract.
Input: A diff, PR link, or AI-generated deliverable.
Cowork action: Apply the five-axis review from iac:code-review-and-quality (correctness, clarity, security, performance, testability). Produce a numbered redline with evidence: file:line, what's wrong, what to do instead.
Handoff: Eric pastes the redline into the PR or hands it to Claude Code as a fix prompt.
Input: A failing test, broken build, or runtime error.
Cowork action: Run the iac:debugging-and-error-recovery triage (Reproduce → Localize → Reduce → Root-cause → Guard → Verify). Produce a written root-cause note and a minimal reproduction.
Handoff: The root-cause note goes into SESSION.md "Known Issues" and feeds the next Claude Code session.
In all three patterns, Cowork writes the spec or the redline; Claude Code executes it. That division of labor is the point.
Two modes, one philosophy: AI is a collaborator, not a command shell. Pair mode is for thinking together. Delegation mode is for handing off bounded work with a written spec. Cowork is where specs and reviews live. Claude Code is where the code gets written. Ruflo is where work parallelizes.
The ten principles — Interview-Before-Plan, Plan-Before-Code, Reviewable Units, Extensive Context, Right Model for the Job, Agent Lifecycle Guardrails, Human Accountability, Granular Commits, Customize AI, Testing/Automation, Continuous Learning — apply to both modes. Which principle dominates depends on what you're doing, but none of them is optional.
iac:spec-driven-development — write the spec before writing the codeiac:code-review-and-quality — five-axis review methodologyiac:debugging-and-error-recovery — structured triage when things breakiac:builder-playbook — project archetypes and scaffold recipesiac:github-playbook — repo workflow and multi-machine setupiac:agent-landscape — frameworks, personas, marketplace strategy