Agent Foundry

Skill

plan-before-code

No implementation without an agreed spec for non-trivial work. Brainstorm, write the spec, confirm it, then code. Use before any feature, component, behavior change, or refactor with more than one reasonable approach.

Category
core
Version
0.2.0
License
MIT
Status
active
Length
98 lines
Source
skills/core/plan-before-code/SKILL.md

Install and discovery

npx --yes --package @youcisla/agent-foundry agent-foundry-install

After the installer runs, this record is available as plan-before-code. See the docs for harness roots and verification steps.

Contents

Plan Before Code

The gate between an idea and a change. It is proportional: the spec for a small change is a paragraph, not a document.

Procedure

1 - Decide whether the gate applies

Apply it when the work is non-trivial, has more than one reasonable approach, is hard to reverse, or the user has not already authorized the change.

Skip it when:

  • The change is a one-line typo or a trivial mechanical edit.
  • The user already provided a clear, complete spec and authorized the work.
  • The artifact is a throwaway script that will be deleted immediately.

Do not demand a second approval the user has already given.

2 - Clarify only the real gaps

Ask one question at a time, and only when the answer changes the design. If the request is clear, state your assumptions and continue. Do not dump a checklist of questions to appear thorough.

When approaches differ materially, name two or three with tradeoffs and a recommendation.

3 - Draft the spec

Save under plans/specs/ or the project's existing spec location. Sections:

  • Goal: one sentence
  • Success criteria: observable, not vibes
  • Non-goals: what is explicitly excluded
  • Approach: chosen path and rationale
  • Steps: ordered, each with a check
  • Risks: what could fail and the mitigation
  • Open questions: unresolved items

4 - Confirm when confirmation is needed

Ask for review when the decision is genuinely user-owned or irreversible. When the user already authorized the work and the spec matches their request, record the spec and proceed.

5 - Implement and keep the spec honest

Follow the steps. If reality diverges, update the spec before changing the implementation again. Report where the spec changed.

Why it works

  • Surfaces unstated assumptions before they become code.
  • Gives the work a reference when it gets fuzzy.
  • Makes a bad approach cheap to abandon.

Worked example

A spec skeleton small enough to confirm before code exists.

Spec: add cmd export --json.
Success: exit 0 and valid JSON on 3 fixtures.
Non-goals: remote upload, resumable export.
Step 1: parse args -> test parse_args.

Anti-patterns

  • Applying a heavyweight spec process to a typo.
  • Requiring approval after the user has already authorized the work.
  • Writing a spec that restates the request without success criteria.
  • Treating the spec as immutable when the source disagrees.
  • Asking ten clarifying questions whose answers do not change the design.

Verification Checklist

  • [ ] The gate was applied proportionally, or a skip reason is stated. (step 1)
  • [ ] Success criteria are observable. (step 3)
  • [ ] Non-goals are explicit. (step 3)
  • [ ] Each implementation step has a verification. (step 5)
  • [ ] The user was not asked to approve work they already authorized. (step 4)

View the source on GitHub

← Back to all skills and agents