# Spec Before Code

> Michel's lightweight design-doc workflow — write a markdown spec under `specs/` before implementing any non-trivial feature, including a threat model. Use whenever the user proposes a new feature, a non-trivial refactor, a new service / endpoint / data flow, an integration with an external system, or anything touching auth, secrets, PII, or multi-tenant data. Triggers on phrases like "let's add",…

- **Type:** Skill
- **Install:** `agentstack add skill-m2laborg-agent-skills-spec-before-code`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [M2LabOrg](https://agentstack.voostack.com/s/m2laborg)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [M2LabOrg](https://github.com/M2LabOrg)
- **Source:** https://github.com/M2LabOrg/agent-skills/tree/main/spec-before-code
- **Website:** https://m2laborg.github.io/agent-skills/

## Install

```sh
agentstack add skill-m2laborg-agent-skills-spec-before-code
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Spec Before Code

For non-trivial work, draft a short markdown spec **before** writing code. Specs prevent over-engineering, surface unknowns, and create a record of *why* a design was chosen.

## When to Write a Spec

Write one when **any** of these is true:

- Estimated effort > 1 day of work
- Touches authentication, authorization, secrets, PII, or multi-tenant boundaries
- Adds a new service, queue, table, bucket, endpoint, or external integration
- Changes a public API contract (request/response shape, status codes)
- Affects more than one container / service / repo
- The user explicitly asks for a "design doc", "RFC", or "spec"

For everything else (bug fixes, small features, refactors), skip the spec and go straight to implementation — but capture the decision in the PR description.

## Folder Layout

```
specs/
├── README.md                    # Index of specs (one-line summary each)
├── 0001-feature-name.md         # Numbered, kebab-case
├── 0002-another-feature.md
└── archive/                     # Specs whose features have shipped (optional)
```

Number specs sequentially. Don't reuse numbers.

## Spec Template (Use Exactly)

```markdown
#  — 

**Status:** Draft | In review | Accepted | Implemented | Superseded by #NNNN | Rejected
**Author:** Michel  **Date:**   **Reviewers:** 
**Related:** PBI #, Issue #, Spec #

## Problem

## Goals
- 
- ...

## Non-Goals
- 
- ...

## Constraints
- 

## Proposed Design

### Architecture
```mermaid

```

### Data Model

### API / Interface

### Failure Modes

## Threat Model

## Alternatives Considered
1. **** — . Rejected because .
2. **** — ... Rejected because ...

## Migration / Rollout

## Open Questions
- [ ] 
- ...

## Test Plan

## Success Metrics

```

## Threat Model — Always Include

Every spec includes a threat model section, even for "boring" features. Use the **STRIDE** framework, or the lighter "assets / actors / threats / mitigations" form below.

```markdown
## Threat Model

### Assets
- 

### Actors / Trust Boundaries
- 
- 

### Threats (STRIDE)
| Category | Threat | Likelihood | Impact | Mitigation |
|---|---|---|---|---|
| Spoofing |  | Low/Med/High | Low/Med/High |  |
| Tampering |  | ... | ... | ... |
| Repudiation |  | ... | ... | ... |
| Information disclosure |  | ... | ... | ... |
| Denial of service |  | ... | ... | ... |
| Elevation of privilege |  | ... | ... | ... |

### Residual Risks

### Secrets & PII
- 
- 
```

For features with no realistic security surface, you can shorten this to one paragraph — but always include it. The act of writing it forces the question.

## Discipline

- **Specs are short.** Aim for 1–3 pages of markdown. If it's longer, the design probably isn't crisp yet.
- **Spec the problem, not just the solution.** A spec that skips "Problem" is a recipe for solving the wrong thing.
- **Diagram with Mermaid**, not ASCII. See the `mermaid-diagrams` skill.
- **Reviewable in a PR.** Open the spec as its own small PR before the implementation PR, so the design conversation happens on the spec, not on 800 lines of code.
- **Status field is real.** Update it as the spec moves through review and implementation.
- **Archive after shipping.** Move implemented specs to `specs/archive/` (or just leave them in place with `Status: Implemented`) so the history stays.

## Anti-Patterns

- Skipping the spec because "it's faster" — and rebuilding twice.
- "Goals" that are just a feature description; missing measurable outcomes.
- Empty "Alternatives Considered" — at least one alternative was real, document it.
- Threat model = "no security implications". Almost never true; force yourself to think about it.
- Spec that becomes stale because nobody updates `Status` after implementation drifts.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [M2LabOrg](https://github.com/M2LabOrg)
- **Source:** [M2LabOrg/agent-skills](https://github.com/M2LabOrg/agent-skills)
- **License:** MIT
- **Homepage:** https://m2laborg.github.io/agent-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-m2laborg-agent-skills-spec-before-code
- Seller: https://agentstack.voostack.com/s/m2laborg
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.