🧰 AI Development Context Framework

Specifications, guardrails, and project memory for coding Agents.

🧭  Your coding Agent keeps losing product intent, architecture choices, and task context between sessions? 📚  A small project needs a light setup while a larger one needs durable specifications and handoffs? 🔒  You want the Agent to maintain progress freely while protecting decisions that require approval?

✨ Turn product discussion into a living context system for coding Agents.

Discuss → specify → initialize → build → maintain context

🧩 Editions · ✨ Highlights · 🗺 Workflow · 📦 Files · ⚡ Install · 🚀 Usage · 🛡 Principles · 🎬 Example · 📂 Structure · 📌 Notes

English · 简体中文 · Español · Deutsch · 日本語 · Русский · Português · 한국어

---

🧩 Choose an edition

	Full	Lite
Skills	spec-gen, project-init, readme-craft	spec-gen-lite, project-init-lite
Project files	3 core files, up to 9 when triggered	3 core files
Task model	Priority queue, triage headers, issues, decisions, and handoffs	Phase queue with [S/M/L/XL] sizing
Best fit	Multi-module work, longer projects, multiple sessions, or team handoffs	Focused solo projects, prototypes, and short delivery cycles
Install source	skills/	lite/skills/

Both editions live in this repository. Install one edition in a coding environment so the two pairs of overlapping Skill triggers stay unambiguous.

---

✨ Three Skills, one framework

Skill	Input	Output	Place in the workflow
spec-gen	Product discussion and constraints	A structured SPEC.md	First: define the product
project-init	An existing SPEC.md	Project guidance and management files	Second: prepare the coding environment
readme-craft	Repository facts and audience	A polished project README.md	Standalone: explain the project publicly

The core development path uses spec-gen followed by project-init. readme-craft is an independent documentation Skill included in the same repository.

---

🗺 Workflow

flowchart LR
    A([Discuss product]) --> B[spec-gen]
    B --> C[SPEC.md]
    C --> D[project-init]
    D --> E[CLAUDE.md]
    D --> F[TODO.md]
    D -. when needed .-> G[ARCHITECTURE · SCHEMA · DESIGN]
    E --> H([Coding Agent])
    F --> H
    G --> H
    H -. first issue .-> I[ISSUES.md]
    H -. first decision .-> J[DECISIONS.md]
    H -. cross-session handoff .-> K[PROGRESS.md]
    H --> L([Build with context])

    M([Repository facts]) --> N[readme-craft]
    N --> O[README.md]

    style A fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#000
    style B fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style C fill:#EDE9FE,stroke:#8B5CF6,stroke-width:2px,color:#000
    style D fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style E fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#000
    style F fill:#F1F5F9,stroke:#64748B,stroke-width:1px,color:#000
    style G fill:#F8FAFC,stroke:#94A3B8,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style H fill:#DCFCE7,stroke:#22C55E,stroke-width:2px,color:#000
    style I fill:#FEF2F2,stroke:#EF4444,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style J fill:#FFFBEB,stroke:#F59E0B,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style K fill:#F0FDF4,stroke:#22C55E,stroke-width:1px,stroke-dasharray:4 4,color:#000
    style L fill:#DCFCE7,stroke:#22C55E,stroke-width:2px,color:#000
    style M fill:#FEF3C7,stroke:#F59E0B,stroke-width:2px,color:#000
    style N fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style O fill:#EDE9FE,stroke:#8B5CF6,stroke-width:2px,color:#000

Loading

project-init reads the SPEC and decides how much structure the project needs. It also writes natural-language maintenance rules into CLAUDE.md. An Agent that follows those rules can create state-bearing files when their first real trigger occurs; no runtime hook enforces this behavior.

---

📦 What gets generated

Core files

File	Source	Purpose
SPEC.md	spec-gen	Product scope, modules, constraints, data needs, and MVP boundary
CLAUDE.md	project-init	The Agent entry point, permissions, repository map, and automation rules
TODO.md	project-init	A prioritized queue with a focused current-task section

Added when the SPEC calls for them

File	Trigger	Purpose
ARCHITECTURE.md	Three or more functional modules	System structure, dependencies, interfaces, and data flow
SCHEMA.md	A database or complex data model	Entities, fields, constraints, indexes, and migrations
DESIGN.md	A user interface	Visual system, components, flows, states, and responsive behavior

Created during development

File	First trigger	Purpose
ISSUES.md	A bug, technical problem, limitation, or open question	Structured issue tracking with status and module IDs
DECISIONS.md	A technical or architectural choice	Decision records, rejected options, and reversibility level
PROGRESS.md	The first cross-session handoff	Current phase, blockers, milestones, and restart point

The framework starts with three files and can grow to nine. Each additional file has a concrete trigger.

---

⚡ Install

These instructions install the Full edition. For the three-core-file setup, use the Lite installation guide.

Give Claude Code this line:

Remove the five managed Full and Lite Skill directories from the target scope, then install all three Full Skills from https://github.com/okht/ai-dev-context-framework/tree/main/skills.

🛠️ Install manually

Clone the repository:

git clone --depth=1 https://github.com/okht/ai-dev-context-framework.git

Install globally for Claude Code and clean any managed Lite Skills:

bash ai-dev-context-framework/scripts/sync-skills.sh full

Install into the current project and clean any managed Lite Skills:

mkdir -p .claude/skills
rm -rf .claude/skills/spec-gen .claude/skills/project-init .claude/skills/readme-craft .claude/skills/spec-gen-lite .claude/skills/project-init-lite
cp -r ai-dev-context-framework/skills/* .claude/skills/

Start a new Claude Code turn after installation so the Skill index refreshes.

For development on this repository, the bundled sync script copies the current skills/ directories into ~/.claude/skills/:

bash scripts/sync-skills.sh full

The sync script removes the five managed Full and Lite Skill directories, then copies the selected Full edition. Unrelated global Skills remain in place. Review the script and the destination before running it.

Other AI coding tools can use the Markdown instructions and templates directly. Skill discovery and invocation syntax depend on the host.

---

🚀 Usage

1. Turn the discussion into a SPEC

/spec-gen

Or ask naturally:

Turn our product discussion into a structured SPEC.

spec-gen writes SPEC.md, covering product overview, feature modules, non-functional requirements, data needs, technical constraints, MVP scope, and glossary.

2. Initialize the project context

/project-init

project-init checks for SPEC.md, creates the core files, evaluates conditional files, and embeds maintenance rules for later development.

3. Create a public project guide

/readme-craft

Use readme-craft independently when the repository needs a clear public-facing README based on verified project facts.

---

🛡 Design principles

Principle	How the framework applies it
LLM-readable structure	Stable headings, explicit relationships, tables, and plain-text rules
Prompt-level permissions	Locked and generated regions tell the Agent what the workflow expects it to change
Process and decision split	Routine progress can move quickly while product and architecture changes require approval
Complexity-scaled files	Small projects stay light; additional files appear from explicit signals
Bounded document size	A SPEC above 300 lines prompts a module split into docs/spec/
Deterministic summaries	State headers are rebuilt from counts, modules, IDs, and dates

Locked and generated zones

Generated files mark their boundaries with HTML comments:

<!-- 🔒 START 锁定区：规则 -->
Rules the Agent must preserve
<!-- 🔒 END 锁定区：规则 -->

<!-- 🔓 START 生成区：项目内容 -->
Project-specific content the Agent can maintain
<!-- 🔓 END 生成区：项目内容 -->

The generated instructions require user confirmation before substantive changes to SPEC.md, ARCHITECTURE.md, SCHEMA.md, DESIGN.md, and DECISIONS.md. Process files such as TODO.md, ISSUES.md, and PROGRESS.md are intended for routine Agent maintenance. These controls are conventions in Markdown and depend on Agent compliance.

Fast triage headers

TODO.md, ISSUES.md, PROGRESS.md, and DECISIONS.md begin with a compact, mechanically derived status block.

File	Header focus
TODO.md	In-progress count, backlog distribution, next action, update date
ISSUES.md	Active modules, first relevant item, state counts, MVP blockers
PROGRESS.md	Phase, milestone progress, blockers, restart point
DECISIONS.md	Irreversible decisions, count, and update date

Each template includes the rebuild algorithm in a locked section. After changing the body, the Agent recomputes the complete header from the source entries.

---

🎬 Example: ChatLens

The examples/ directory contains a filled set for ChatLens, a fictional B2B conversation-analytics product.

What the example shows	Important context
All nine project files	They were intentionally generated together to demonstrate every template
Locked and generated regions	The permission model in realistic documents
Triage headers and algorithms	How state summaries stay mechanically derived
Cross-file references	How tasks, issues, decisions, and progress connect

Real projects follow the trigger rules. A small project may use only SPEC.md, CLAUDE.md, and TODO.md.

---

📂 Project structure

ai-dev-context-framework/
├── README.md
├── LICENSE
├── scripts/
│   └── sync-skills.sh
├── skills/
│   ├── spec-gen/
│   │   ├── SKILL.md
│   │   └── templates/SPEC.md.example
│   ├── project-init/
│   │   ├── SKILL.md
│   │   └── templates/*.md.example
│   └── readme-craft/
│       ├── SKILL.md
│       ├── agents/openai.yaml
│       ├── references/
│       │   ├── visual-system.md
│       │   └── verification.md
│       ├── scripts/validate_readme.py
│       └── templates/README.md.example
├── lite/
│   ├── README.md
│   ├── WORKFLOW.md
│   └── skills/
│       ├── spec-gen-lite/SKILL.md
│       └── project-init-lite/SKILL.md
└── examples/
    ├── SPEC.md
    ├── CLAUDE.md
    ├── TODO.md
    ├── ARCHITECTURE.md
    ├── SCHEMA.md
    ├── DESIGN.md
    ├── ISSUES.md
    ├── DECISIONS.md
    └── PROGRESS.md

The repository stores Skills, reusable templates, a complete example, and one developer sync helper. It contains no application runtime.

---

📌 Notes

• spec-gen and project-init form the core project workflow.
• readme-craft is a standalone README-writing Skill.
• lite/ is the three-core-file edition maintained in the same repository.
• Install either the Full or Lite edition in one coding environment to avoid overlapping Skill triggers.
• project-init expects an existing, complete SPEC.md.
• The nine-file ChatLens set is a showcase; normal output scales with project complexity.
• scripts/sync-skills.sh full|lite cleans the other managed edition before copying the selected global Skills.
• The repository currently distributes source Skill folders and does not publish packaged .skill releases.

Issues and pull requests are welcome.

---

Keep product intent, implementation context, and project state in the same system.

MIT License © okht