linkspawn-create-context

README

linkspawn-create-context

spawn scaffolds an AGENTS.md operating contract plus a .context/ memory system for AI-agent-driven development — guardrails, project state, architecture notes, decision logs, and a lessons loop, as plain markdown that any coding agent (Claude Code, Codex, Cursor, Antigravity, or the next one) can load.

$ spawn init

  created .context/ARCHITECTURE.md
  created .context/DECISIONS.md
  created .context/LESSONS.md
  created .context/PROJECT_STATE.md
  created .context/README.md
  created .gitignore
  created AGENTS.md
  created CLAUDE.md

✓ core preset scaffolded for "my-project".

Why

AI coding agents are stateless. Every session starts cold: the agent doesn't know your guardrails, your locked decisions, your definition of done, or the mistake it made last Tuesday. Most people re-explain these every session — or worse, don't, and pay for it.

The .context/ system externalises that knowledge into durable, tool-agnostic plain text:

File	Job
AGENTS.md (repo root)	The operating contract: hard guardrails, definition of done, what to do when things go wrong
.context/PROJECT_STATE.md	Shared memory across sessions and agents — phase, active work, blockers. Updated every session
.context/ARCHITECTURE.md	System design and module boundaries, so agents stop guessing
.context/DECISIONS.md	Append-only log of locked decisions, so agents stop relitigating them
.context/LESSONS.md	Rules learned from corrections, read at session start — the agent stops repeating its mistakes
CLAUDE.md	Thin root alias so tools reading that filename land in the same cascade

The contract sits at the repo root as AGENTS.md because that is the cross-tool standard — Codex, Cursor, and Antigravity read it natively, with no per-vendor shim. .agents/skills/ is left alone for vendor CLIs that write skills there (neonctl init and friends); spawn never scaffolds into it and never gitignores it.

These templates weren't written for this repo — they were distilled from years of running this system across real commercial and personal projects, then extracted into a scaffolder. The patterns that survived are the ones that earn their keep.

Install

Homebrew (macOS / Linux):

brew install LinkSpawnDev/tap/spawn

Go toolchain:

go install github.com/LinkSpawnDev/linkspawn-create-context/cmd/spawn@latest

Or grab a prebuilt binary for macOS, Linux, or Windows from the releases page.

Use

cd your-project
spawn init                     # interactive: name, mission, owner, runner, preset
spawn init --yes               # accept defaults, no prompts (scripting/CI)
spawn init --preset minimal    # just a root AGENTS.md + CLAUDE.md alias
spawn init --runner "uv run"   # script runner for the Definition of Done gates
spawn init --no-claude-alias   # skip the CLAUDE.md alias
spawn init --force             # overwrite existing files

spawn never overwrites your files unless you pass --force, and it appends to an existing .gitignore rather than replacing it. Re-runs are idempotent.

The generated Definition of Done is a script contract, not a tool list — --runner sets the prefix (npm run by default, or make, uv run, cargo, go), so the gates read make lint / make test and the underlying tools can change without anyone editing AGENTS.md.

Presets

• core (default) — root AGENTS.md contract plus the full .context/ memory tier. For any project an agent will work in more than once.
• minimal — a single condensed AGENTS.md at the root plus a CLAUDE.md containing @AGENTS.md. For repos too small to justify a folder.

The method, in five rules

1. Guardrails are absolute. The agent never commits, never pushes, never publishes, never invents facts to fill gaps. Drafting is the agent's job; signing is yours.
2. State is updated every session. PROJECT_STATE.md is the handoff between today's agent and tomorrow's — honest about what works, what doesn't, what's stubbed.
3. Decisions are append-only. A locked decision is superseded, never rewritten — and never silently "fixed" by a helpful agent.
4. Stop-rules beat cleverness. When a test fails unexpectedly or data is missing, the right move is stop and raise, not improvise. The templates pre-authorise that.
5. Corrections become rules. Every "no, don't do that" gets written to LESSONS.md and re-read at session start. The quality test for every rule: would removing this line cause a specific mistake?

Everything is markdown. Nothing is coupled to one vendor's tool. When a tool dies — and tools die — nothing of yours dies with it.

Upgrading from v0.1

v0.2.0 ships template spec v1.1, which changes the shape of generated output: the contract moved from .context/AGENTS.md to the repo root as AGENTS.md, GEMINI.md is gone (Gemini CLI shut down 2026-06-18; Antigravity reads AGENTS.md), and CLAUDE.md became a thin alias. Existing repos keep working — nothing rewrites itself. To migrate one by hand:

1. git mv .context/AGENTS.md AGENTS.md (preserves history as a rename)
2. Prefix the moved file's internal references with .context/
3. Delete GEMINI.md; replace CLAUDE.md with the thin alias
4. Update the load order in .context/README.md
5. Append a superseding decision entry to .context/DECISIONS.md — never silently restructure a repo that records its own decisions

spawn doctor --fix will automate exactly this. Scaffolds from v0.2.0 onward carry a spec v1.1 stamp in each file header so doctor can tell the vintages apart.

Roadmap

• spawn doctor [--fix] — validate an existing .context/: broken links, stale state, naming drift, junk files, and the v1.0 → v1.1 layout migration above
• spawn add <module> — optional modules (ADR folder, session log, skills)
• spawn lesson "<title>" — append a correctly-formatted lesson without opening the file

Licence

MIT. Built by LinkSpawn.