agentleFS
haqalizhaqaliz/assay/.claude/skills/tech-plan/SKILL.md

tech-plan

Skill0 starsChanged 3 days agoApache-2.0View on GitHub

Create a phased technical implementation plan from planning artifacts in docs/planning (PRD + aspect spec). Use after prd-interview when ready to execute a specific aspect. Triggers on "tech plan", "implementation plan", "plan from PRD".

  • Reads credentials

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. PierreTsia/workout-app★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository10 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Create a phased technical implementation plan from planning artifacts under docs/planning/{slug}/.

    line 11
  2. Distinctive:

    If the user provided artifacts in context, use them directly.

    line 15
  3. Very specific:

    Greenfield: if pyproject.toml / uv.lock / src/ don't exist, scaffolding them is part of the plan's first phase — say so explicitly.

    line 40
  4. Distinctive:

    Commit message. Each phase is a unit the agents team can own end-to-end under TDD.

    line 46
  5. Distinctive:

    Don't plan work that rests on a static pattern match or a model opining on a skill's text as the verdict — flag it against CLAUDE.md's …

    line 82
  6. Very specific:

    Incomplete PRD: If it lacks testable acceptance criteria, flag it and recommend prd-interview.

    line 91

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Create a phased technical implementation plan from planning artifacts under docs/planning/{slug}/. Inputs can come directly from prd-interview; do not require prd-generator. This is Phase 5 of assay-begin-fast — the plan it produces is executed in Phase 6 through the agents team under strict TDD.

If the user provided artifacts in context, use them directly. Otherwise, search:

  • PRDs matching docs/planning/*/prd.md
  • Aspect specs matching docs/planning/*/*/spec.md

Analyze the current codebase, then create a detailed Implementation Plan. Assay is greenfield: today the authoritative reading is docs/technical/CAPABILITY_ROADMAP.md (A1..A10, dependencies, guardrail tie-ins), docs/technical/ARCHITECTURE.md (the design), and docs/ROADMAP.md (phases, milestones, R1..R9); the engine will live under src/assay/ once it exists.

Handoff Contract

  • Feature requirements source: docs/planning/{slug}/prd.md
  • Aspect requirements source (preferred): docs/planning/{slug}/{aspect}/spec.md
  • Plan output (required): docs/planning/{slug}/{aspect}/plan_YYYYMMDD.md

Plan one aspect at a time.

Deliverables

1. Project Setup Checklist

  • Directory/module structure under src/assay/, tests/.
  • Configuration (pyproject entries, env, sandbox limits).
  • Dependencies via uv add.
  • Greenfield: if pyproject.toml / uv.lock / src/ don't exist, scaffolding them is part of the plan's first phase — say so explicitly. Test-first still holds.

2. Implementation Phases

For each phase: Goal, Prerequisites, Files to create/modify, Validation (uv run pytest <path>), Commit message. Each phase is a unit the agents team can own end-to-end under TDD.

3. File-by-File Build Order

Filepath, one-line purpose, key exports, dependencies.

4. Testing Strategy

  • Unit tests mapped to phases, written first.
  • Integration tests. Manual verification steps.
  • Start from the capability's acceptance intent. CAPABILITY_ROADMAP.md and the aspect spec.md state what each capability must do; lift those into tests before the code. Sandbox and agent-driver tests are deterministic and run with no real sandbox and no real model call — any live run sits behind an injectable seam using recorded traces in CI.

5. Environment & Determinism

  • Env vars (BYOK keys stay in .env, never committed, never a default).
  • Local setup: uv sync.
  • A verdict must be re-derivable from the signed bundle alone. A test whose result depends on clock, network, or random ordering is a bug in the plan.

6. Edge Cases & Error Handling

  • Given Assay's contract, name the explicit UNVERIFIED cause for anything that can fail to evaluate (WONT_PARSE, SANDBOX_FAILED, AGENT_FAILED, COST_CAPPED, NO_TRIGGER, TRACE_INCOMPLETE). A harness-side failure is UNVERIFIED, never MALICIOUS.

7. Agent Execution Notes

  • Checkpoints for human review, areas likely to need iteration, where the agent should ask for clarification.

Guidelines

  • Be extremely explicit. Prefer small, testable increments.
  • Each phase should result in runnable (even if incomplete) code, suite kept green.
  • Don't plan work that rests on a static pattern match or a model opining on a skill's text as the verdict — flag it against CLAUDE.md's wedge; the sandboxed, observed run decides.
  • Respect the capability build order: A3 needs A1+A2; A4 needs A2+A3; A6/A7 need A5; A9 needs A5-A7. Abstractions are earned by the second implementation, not designed for the first.

Edge Cases

  • Greenfield vs. existing codebase: For greenfield, include full setup.
  • No aspect spec exists yet: Derive candidates from the PRD, ask the user to choose, draft spec.md, confirm, then plan.
  • Incomplete PRD: If it lacks testable acceptance criteria, flag it and recommend prd-interview.
  • Multiple PRDs: Separate plans unless they share infrastructure.
  • PRD with flagged gaps: Note these in the plan and recommend resolution before the affected phase.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.