forge-technical-design
Skill0 starsChanged 3 months agoMITView on GitHub
Turns an approved specification into a technical design — two or three compared approaches, a reasoned recommendation, then architecture, data model, module boundaries, error handling and test strategy. Presents the design section by section with approval after each, and produces specs/<capability>/design.md. Use this skill whenever the user asks for an architecture, a stack choice, a data schema, a technical design, "how do I build this", or as soon as a specification is approved — and before any code is written, even when the approach seems obvious.
In this repository6 other files it gives its agents.
- forge-consistency-reviewSkill
- forge-constitutionSkill
- forge-decision-recordSkill
- forge-idea-framingSkill
- forge-orchestratorSkill
- forge-specificationSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Never present a single option.
- Distinctive: line 42
When two approaches are close, break the tie on reversibility: prefer the one you can undo.
- Distinctive: line 86
Before finalising, run the design through this filter.
- Very specific: line 98
Write specs/<capability>/design.md (template in references/templates.md), open an ADR for each structural decision via the ADR skill, then …
- Distinctive: line 101
After the review, stop. The forge ends here.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
Technical design
Input: an approved spec and a constitution. Output: a design document approved section by section. No code in between.
You are designing for one person. The dominant criterion is not elegance but total cost: build it, operate it, understand it in six months, and undo it if you were wrong.
Step 1 — Explore before proposing
On an existing codebase, read first: folder structure, modules near the target capability, the last few commits, dependencies already present. Follow existing patterns rather than importing new ones. An inconsistency in style costs more than an imperfect pattern.
Where existing code has a problem that directly affects the work — a file that has grown huge, a blurred boundary, tangled responsibilities — include a targeted improvement in the design, the way a good developer improves the code they pass through. Don't propose refactoring unrelated to the current goal.
Step 2 — Two or three approaches, with a trade-off
Never present a single option. A single design is an unexamined design.
For each approach, state:
- What it is in three sentences.
- What it costs to build, in order of magnitude (solo person-days).
- What it costs to operate: how many things to watch, back up, patch, and how it behaves when it fails.
- What it locks in: reversible in a day, or a structural decision?
- The constitution principle that eliminates it, where applicable.
Then recommend explicitly, leading with the recommended option and explaining why. A comparison without a recommendation shifts the cognitive load onto the human — that is your job, not theirs.
When two approaches are close, break the tie on reversibility: prefer the one you can undo. On a reversible decision, speed beats analysis.
Step 3 — Present in sections
Present the design section by section, asking after each whether it holds. A section runs from a few sentences to 300 words depending on its complexity — don't pad what is simple.
An objection to section 2 should be raised before you have written section 6. That is the whole point of the split.
Expected sections:
- Overview — the components and what flows between them. A text or Mermaid diagram is enough; it must fit on one screen.
- Module boundaries — for each unit: what it does, how you use it, what it depends on. Boundary quality test: can you understand the unit without reading its internals, and change its internals without breaking its callers? If not, the boundary is misplaced. Small, well-bounded units are not merely elegant: they are also the only ones an agent modifies reliably, because they fit whole in context.
- Data model — entities, relations, uniqueness constraints, what is indexed and why. State the migration strategy; it is the hardest decision to undo.
- Main flows — for the two or three journeys that matter, the end-to-end sequence. A sequence diagram if more than three actors exchange messages.
- Errors and degraded modes — for each external dependency: what the system does when it is slow, absent, or answers wrongly. Retries, timeouts, idempotency. This is the section people skip and the one that costs the most.
- Security and personal data — where secrets live, who accesses what, what is logged (and especially what must not be), retention.
- Test strategy — which paths deserve an automated test, which are checked by hand and why. Solo, the criterion is not coverage but: "which test would have woken me if I had broken this?"
- Traceability — a requirement → component table. Every requirement in the spec must appear; any component without a requirement is invented scope.
- Deferred decisions — what you deliberately choose not to settle now, and the signal that will force the call.
Anchor the design in the constitution
Explicitly cite the principles that eliminated an option: "P3 (single store) rules out approach B, which adds a search engine." If the recommended design violates a principle, you do not push through: you open an ADR or propose an amendment.
The anti-over-engineering filter
Before finalising, run the design through this filter. Every "yes" needs a written justification in the document:
- Is there more than one service to deploy? More than one state store?
- Is there an abstraction with exactly one implementation? (An interface with a single adapter is not flexibility, it is indirection.)
- Is there a queue, cache or scheduler added "for load" when the spec's volume doesn't justify it?
- Is there a component the human has never operated in production?
- Can the system be rebuilt from scratch on a fresh machine with a written procedure?
Artifact and exit
Write specs/<capability>/design.md (template in references/templates.md), open an ADR for
each structural decision via the ADR skill, then pass through the consistency review gate.
After the review, stop. The forge ends here. Moving to implementation is the human's explicit decision, taken on a document they have read.
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
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.

