██████╗████████╗██╗  ██╗███████╗██╗      ██████╗ ██╗    ██╗
██╔════╝╚══██╔══╝╚██╗██╔╝██╔════╝██║     ██╔═══██╗██║    ██║
██║        ██║    ╚███╔╝ █████╗  ██║     ██║   ██║██║ █╗ ██║
██║        ██║    ██╔██╗ ██╔══╝  ██║     ██║   ██║██║███╗██║
╚██████╗   ██║   ██╔╝ ██╗██║     ███████╗╚██████╔╝╚███╔███╔╝
 ╚═════╝   ╚═╝   ╚═╝  ╚═╝╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝

Context scaffolding for AI agent-driven development.
_{Give your AI the context it needs — before it starts guessing.}

---

The problem

You open your AI coding assistant and ask it to implement a feature. It starts writing code — but it doesn't know your stack, your constraints, your architecture decisions, or what's already been agreed upon.

So it guesses. And you spend the next hour correcting it.

ctxflow fixes this.

It scaffolds structured context files your AI can read before touching a single line of code: requirements, task plans, architectural decisions, and project-wide rules — all in plain Markdown, all version-controlled alongside your code.

---

Install

npm install -g ctxflow

---

Quick start

# 1. Initialise your project (once) — pick your AI agents
ctxflow init

# 2. Create a feature context before you start coding
ctxflow new user-authentication

# 3. Fill in requirements.md — your AI reads this first
# 4. Check progress at any time
ctxflow status user-authentication

Or just run ctxflow for the full interactive menu.

---

What gets created

ctxflow init

Asks which AI agents you use, then creates the right context file(s) for each:

Agent	File
Claude Code	CLAUDE.md
Codex CLI (OpenAI)	AGENTS.md
Cursor	.cursor/rules/project.md
GitHub Copilot	.github/copilot-instructions.md
Windsurf	.windsurfrules
Gemini CLI	GEMINI.md
Cline	.clinerules
Aider	CONVENTIONS.md
Amazon Q	.amazonq/rules/context.md
Continue	.continuerules
Devin / Kiro / others	AGENTS.md

Each file contains your stack, architecture overview, approved libraries, and non-negotiable rules — the single source of truth your AI reads every session.

You can select multiple agents. Files that share a path (e.g. Codex CLI + Devin both use AGENTS.md) are written once.

ctxflow new <feature>

docs/features/<feature>/
  requirements.md       ← Why this feature exists, constraints, acceptance criteria
  plan.md               ← Tasks (checkboxes), file structure, open questions

---

Interactive menu

Run ctxflow with no arguments for a full interactive experience:

  What would you like to do?

  [1]  New feature      — scaffold a new feature context
  [2]  Init project     — create AI context file(s) + /docs structure
  [3]  List features    — show all existing plans
  [4]  Status           — check tasks in a feature plan
  [5]  Help             — show usage and documentation

  Ctrl+C to exit

Press a number key to execute instantly — no Enter needed.

---

CLI reference

Command	Description
ctxflow	Launch interactive menu
ctxflow init	Select AI agents and scaffold context file(s)
ctxflow new <feature>	Create a feature context under docs/features/<feature>/
ctxflow list	List all feature contexts with creation dates
ctxflow status <feature>	Show task completion progress for a feature

---

The workflow

1. ctxflow init          →  Pick your agents. Context files written automatically.
2. ctxflow new <feature> →  Before every feature: scaffold requirements + plan.
3. Fill requirements.md  →  Context, constraints, acceptance criteria. Your AI reads this.
4. Code the feature      →  AI works with full context. No guessing.
5. Check tasks off       →  Mark [ ] → [x] in plan.md as you go.
6. ctxflow status        →  See exactly where you are at any time.

---

Why this works

AI coding assistants are only as useful as the context they receive. Without structured context:

Without ctxflow	With ctxflow
Agent guesses at your stack	Agent reads your exact stack from the context file
Unapproved libraries sneak in	Context file lists exactly what's approved
Requirements drift mid-feature	requirements.md is the single source of truth
Agent asks you the same questions every session	Context is version-controlled and always available

---

Works with any AI assistant

ctxflow supports all major AI coding agents out of the box:

• Claude Code — CLAUDE.md
• Codex CLI (OpenAI) — AGENTS.md
• Cursor — .cursor/rules/project.md
• GitHub Copilot — .github/copilot-instructions.md
• Windsurf — .windsurfrules
• Gemini CLI — GEMINI.md
• Cline — .clinerules
• Aider — CONVENTIONS.md
• Amazon Q — .amazonq/rules/context.md
• Continue — .continuerules
• Devin / Kiro / others — AGENTS.md

Select one or more during ctxflow init. The project is considered initialised as long as any of these files exist.

---

Works with any language or framework

ctxflow generates language-agnostic context files. Whether you're building in Java, Python, Go, Rust, TypeScript, or Ruby — fill in your stack, and your AI gets the right context.

---

Requirements

• Node.js 18+
• Works on macOS, Linux, Windows

---

License

MIT © ctxflow contributors