MD-First Development
Write the markdown before the code. A long task starts with a goal file; every page and component gets a .md spec living alongside the code it describes; and /doc keeps those docs in step once the code changes.
Why Markdown First?
AI tools hallucinate when they lack context. A spec file gives the AI everything it needs before it touches a single line of code: purpose, responsibilities, props, logic, and dependencies. The result is more accurate output, fewer corrections, and a codebase that documents itself.
Start With a Goal File
For work that spans many steps or sessions, run /goal "your idea". The agent drafts a one-page goal file in .contextkit/goals/ with 3–7 checkable outcomes, you approve them, and only then does it start building. The goal file is the markdown-first contract for the whole task: it survives context compaction and new sessions, and every outcome gets an independent review before it's ticked.
.contextkit/goals/dashboard.md
--- status: active created: 2026-10-13 --- # Goal: Account dashboard ## Goal Give signed-in users one page with their account summary, recent activity, and quick actions. ## Outcomes - [ ] O1: A user sees balance, usage, and alerts on /dashboard - [ ] O2: A user can page through recent activity, newest first - [ ] O3: Quick actions only show what the user's role allows
See /goal for the full template and build loop.
The 3-Level Hierarchy
Specs exist at three levels. Each level answers a different question.
Level 1 — Architecture
How the system is structured and how the main parts connect.
→ docs/architecture.md
Level 2 — Page / Feature
What this page does, its folder structure, and the components it uses.
→ src/app/dashboard/Dashboard.md
Level 3 — Component
Granular logic and responsibilities of a single component.
→ src/components/Button/Button.mdLevel 1
Architecture
System-wide view. How services, apps, and modules relate. Written once, updated when structure changes.
Level 2
Page / Feature
One spec per page or feature. Includes the folder structure and a map of which components are used and why.
Level 3
Component
One spec per component, colocated in the same folder. Purpose, props, logic, and dependencies.
Level 2: The Page Spec
When a page is made up of multiple components, the page spec does two things: it describes what the page does and maps out the folder structure with links to each component spec. This gives the AI a complete picture before it touches a single component.
src/app/dashboard/Dashboard.md
# Dashboard Page
## Purpose
Main authenticated view. Shows account summary, recent activity, and quick actions.
## Folder Structure
dashboard/
Dashboard.md ← this file
Dashboard.tsx ← page shell, layout only
components/
SummaryCard/
SummaryCard.md ← see component spec
SummaryCard.tsx
ActivityFeed/
ActivityFeed.md ← see component spec
ActivityFeed.tsx
QuickActions/
QuickActions.md ← see component spec
QuickActions.tsx
## Components Used
- SummaryCard — displays key account metrics (balance, usage, alerts)
- ActivityFeed — paginated list of recent events, sorted newest first
- QuickActions — fixed set of shortcut buttons, role-dependent visibility
## Data
Fetches from /api/dashboard on mount. Passes slices to each component.
No component fetches independently.The folder structure in the page spec is the blueprint. When the AI generates or modifies components, it already knows what else lives in that folder and how they relate.
Level 3: The Component Spec
Each component spec lives in the same folder as the component. It is written before any code is created.
src/components/SummaryCard/SummaryCard.md
# SummaryCard ## Purpose Displays a single account metric with label, value, and an optional alert indicator. ## Responsibilities Owns: - Rendering the metric value with correct formatting (currency, %, count) - Showing an alert badge when value exceeds threshold Does NOT own: - Fetching data (receives props only) - Navigation (parent handles clicks) ## Props / API | Name | Type | Required | Description | |-----------|-----------|----------|---------------------------------| | label | string | Yes | Metric label shown above value | | value | number | Yes | Raw numeric value | | format | 'currency' | 'percent' | 'count' | No | Display format | | alert | boolean | No | Show alert badge when true | ## Logic & Behavior - value is always formatted before display — never render raw numbers - alert badge appears top-right, red, only when alert=true - No click handler on the card itself; parent wraps in a link if needed ## Dependencies - formatValue utility (lib/format.ts) - Used by: Dashboard
What It Looks Like in Practice
Every folder that contains code also contains a spec. The .md file and the implementation file are always siblings.
docs/ └── architecture.md ← Level 1 spec (system) src/ ├── app/ │ └── dashboard/ │ ├── Dashboard.md ← Level 2 spec (page) │ ├── Dashboard.tsx │ └── components/ │ ├── SummaryCard/ │ │ ├── SummaryCard.md ← Level 3 spec (component) │ │ ├── SummaryCard.tsx │ │ └── SummaryCard.test.tsx │ ├── ActivityFeed/ │ │ ├── ActivityFeed.md │ │ ├── ActivityFeed.tsx │ │ └── ActivityFeed.test.tsx │ └── QuickActions/ │ ├── QuickActions.md │ ├── QuickActions.tsx │ └── QuickActions.test.tsx
The Workflow
1. Write the page spec first
Define what the page does and sketch the folder structure with component names. Use create-feature to scaffold it from the template. You don't need all the details — just enough to map the shape of the work.
2. Write each component spec
For each component referenced in the page spec, create a colocated ComponentName.md. The create-component workflow scaffolds it from .contextkit/templates/component-spec.md.
3. Review before coding
Read through the specs as a team (or alone). Catch misunderstandings in markdown before they become bugs in code.
4. Generate code from the spec
Use create-component to scaffold implementation. The command reads the spec and uses it as the source of truth for props, tests, and behavior — no re-explaining required.
Commands
Level 2
create-feature
Scaffold a page or feature spec (Level 2). Creates FeatureName/FeatureName.md from the feature template and waits for approval before writing any code.
Create a Dashboard feature with summary, activity feed, and quick actions
Task
/goal
Draft a one-page goal file with checkable outcomes, get your approval, then build outcome by outcome with a fresh-context review of each.
/goal "account dashboard with summary, activity feed, and quick actions"
Level 3
create-component
Scaffold the implementation. Checks for an existing component spec first — if none exists, drafts one from component-spec.md before touching any code.
Create a SummaryCard component
Generating Docs
Once code exists, /doc generates documentation at each level of the hierarchy — tailored to your project's stack (React, Vue, Go, Python, and more). With no argument, it finds the docs and standards that reference code changed on your branch and updates the stale ones.
Level 1 /doc arch → docs/architecture.md Level 2 /doc feature → docs/features/<name>.md Level 3 /doc component → <path>/<name>.md (colocated)
Level 1
/doc arch
Generates or updates docs/architecture.md — system overview, key flows, Mermaid diagrams, and architecture decisions.
/doc arch /doc arch 142 # from PR #142
Level 2
/doc feature
Generates or updates docs/features/<name>.md — purpose, components used, data flow, and user flows for a specific feature area.
/doc feature auth /doc feature apps/billing
Level 3
/doc component
Creates a colocated <name>.md next to the target file — API/props, usage example, behavior, and edge cases.
/doc component src/components/Button.tsx /doc component lib/utils/parser.js
When to use which
| Scenario | Command |
|---|---|
| Finished a change and want every affected doc and standard updated | /doc |
| Merged a PR that changed system boundaries or added a service | /doc arch |
| Shipped a new feature — want to document how it works end-to-end | /doc feature |
| Wrote a new component, utility, or module | /doc component |
| Reviewing a PR and want to understand architecture impact | /doc arch <PR number> |
| Backfilling docs on existing code | /doc component <path> |
Before you push
Run /doc with no argument at the end of a branch. On a feature branch it lists the recommended updates first, then applies them. For npm packages it also suggests a version bump and checks CHANGELOG.md.
The Rule
If a folder contains a .tsx (or .jsx, .vue, .svelte) file, it should also contain a .md spec. No exceptions. The spec doesn't need to be long — a clear Purpose and Responsibilities section is enough to give the AI meaningful context.
Was this helpful?
Help us improve the documentation by sharing your feedback.