Your AI writes code. AIContext teaches it to build features.

Most AI coding sessions lose context, skip planning, and need constant hand-holding. AIContext gives your AI assistant a complete development methodology — it interviews you before coding, creates a plan, executes it step by step with automated reviews and tests, and picks up exactly where it left off when you start a new session.

Works with any language or framework — PHP, Python, JavaScript, TypeScript, Rust, Go, and more.

One workflow. Six coding agents. Your team can use Claude Code, Codex, Cursor, opencode, Pi, or GitHub Copilot without losing its shared specs, task history, quality gates, or delivery process.

Quick Start

npm install -g @zahardev/aicontext
cd /path/to/your-project
aicontext init

Every session must begin with the native start invocation. This loads your project context, rules, and workflow - without it, none of the other commands will work correctly. On first run, the AI will analyze your codebase and generate project context automatically.

Run the native aic-help invocation for a guided tour of available workflows and best practices.

What Makes AIContext Different

Not just context files — a Spec Driven Development workflow

Writing a CLAUDE.md or .cursorrules file gives your AI memory. AIContext gives it a way of working — built on Spec Driven Development, where the spec is the source of truth and code is derived from it:

start-feature  →  Interview  →  Spec + Task(s)
                                      ↓
                                run-task  →  Implement + Review + Test (automated per step)
                                      ↓
                                close-task  →  Mark tracking done, optionally close issue

The AI interviews you before writing code - exploring your codebase to avoid asking what it can determine itself. It recommends answers based on what it found, walks every dimension breadth-first so nothing is missed, and captures decisions as it goes. You confirm or correct - not explain from scratch.

The AI executes the plan - each step is implemented, reviewed, and tested automatically. You supervise rather than drive.

The AI reviews its own code - built-in review catches bugs, security issues, and architectural problems before you even look at the diff.

The AI tests in the browser - the web-inspect skill opens real pages, checks console errors, interacts with elements, and captures screenshots. No more copy-pasting console errors.

The AI drives the process - after every action, the AI tells you what to do next in your tool's own syntax. Finished a step? "Run $next-step to continue." Closed a task? "Spec has more pending tasks - start the next one?" You never have to guess the next command.

The AI adapts to your workflow - on first run, it asks how you like to work: reviews after every step or only at the end? Commit per step or per task? Push automatically? It remembers your answers and never asks again.

The AI remembers across sessions - specs, tasks, and task-contexts capture everything. Start a new session, run the load-task skill, and the AI picks up where it left off. No knowledge is lost.

Three layers of persistent context

| Layer | What it captures | Example | |-------|-----------------|---------| | Spec | What to build and why — requirements, decisions, non-goals | "Users can reset passwords via email. Not supporting SMS." | | Task | How to build it — step-by-step plan with checkboxes | "Step 1: Add reset endpoint. Step 2: Email template. Step 3: Token expiry." | | Task-Context | What the AI learned while building — patterns, gotchas, file references | "Auth middleware checks token in header, not cookie. See src/auth.js:42." |

Specs and tasks are committed to git. Task-context files are gitignored — each developer accumulates their own working knowledge.

Learn more in the development model guide.

Key Features

Structured planning

• start-feature - thorough discovery interview before any code is written
• create-task - quick task creation from conversation when a full interview isn't needed
• plan-tasks - break an existing spec into multiple tasks
• add-idea - capture a deferred idea to the worklog mid-session so it's not lost

Automated execution

• run-task - execute all steps with built-in review and test loops
• run-step - execute a single step with full control
• do-it - turn a conversation into a task step and implement it immediately

Code review

• review - quick correctness scan (bugs, security, edge cases)
• deep-review - comprehensive architecture + correctness + codebase health review
• Specialized reviewer agent runs in parallel without consuming your main conversation (Claude Code)

Agent orchestration

You can make your AI the tech lead and give it a team of agents — it plans and delegates instead of coding.

• orchestrate-workers - a coder, test writer, tester, and reviewer run as separate agents; the lead triages their findings and gates on your approval
• Requires Herdr; Pi workers preferred, other agent kinds on request

Session continuity

• load-task - read spec, task-context, and task to continue exactly where you left off
• load-spec - read a feature spec, linked-task progress, and coverage gaps
• close-task - administrative closure: warn about unfinished work, mark tracking done, optionally close the linked issue
• finish-task - deprecated alias for close-task; no PR or git automation
• align-context - sync all context files with current state

Issue & PR workflow

Draft locally. Publish deliberately. draft-pr never touches GitHub; make-pr is the explicit publishing step.

• draft-issue - draft a GitHub issue from conversation, create it on GitHub, and auto-fill the issue ID in subsequent task filenames
• draft-pr - generate a PR description from task context and git history (local file only)
• make-pr - push the branch if needed and create the PR on GitHub
• run-task owns configured after_task.* finalization after all plan steps, including PR creation/update and optional gh-resolve-pr.
• gh-resolve-pr validates an existing PR's CI, reviews, and mergeability without merging.
• GitHub is supported initially; unsupported providers receive a limitation report.
• gh-review-fix-loop - automate the review-fix-push cycle (works with CodeRabbit, human reviewers, etc.)
• gh-fix-tests - fix failing CI checks automatically: diagnose, fix, push, retry until green

Thinking tools

• interview - structured discovery on any topic - the AI walks dimensions, recommends answers, and captures decisions
• brainstorm - generate missing angles, better implementations, and new combinations
• thoughts - quick "what do you think?" check-in for feedback mid-conversation

Documentation generation

• generate-docs - generate project documentation from code and existing artifacts (reference, guide, or both)

Project maintenance

• prepare-release - generate changelog, update version numbers, and prepare a release commit
• tidy-aic - archive completed tasks and specs, clean up session artifacts, keep the project directory lean

Browser inspection

• web-inspect - open pages, check console errors, interact with elements, capture screenshots

Safety guardrails

• Blocks destructive commands, enforces TDD, requires explicit permission before implementation
• Configurable quality checks: what runs after each step vs after the whole task — adapts to your preferences

See the full skills reference for detailed descriptions of all skills.

How It Works

AIContext creates a .aicontext/ directory with shared rules, prompts, and templates. Each AI tool gets a thin entry point that loads this shared context:

| Tool | How to invoke skills | |------|---------------------| | Claude Code, opencode | /skill-name (e.g., /start-feature) | | Pi | /skill:name (e.g., /skill:start-feature) | | Codex | $skill-name (e.g., $start-feature) | | Cursor, Copilot | use skill-name (e.g., use start-feature) |

Claude Code gets the richest experience with /command skills and parallel subagents. All tools share the same underlying prompts and instructions.

Installation

npm (Recommended)

npm install -g @zahardev/aicontext
cd /path/to/your-project
aicontext init

Or use npx for one-time setup: npx @zahardev/aicontext init

Manual Copy

Clone the GitHub repository and copy the files you need:

git clone https://github.com/zahardev/aicontext.git /tmp/aicontext
cd /path/to/your-project
cp -r /tmp/aicontext/.aicontext .
cp -r /tmp/aicontext/.claude .    # Claude Code
cp -r /tmp/aicontext/.codex .     # Codex
cp -r /tmp/aicontext/.cursor .    # Cursor
cp -r /tmp/aicontext/.opencode .  # opencode
cp -r /tmp/aicontext/.pi .        # Pi
cp -r /tmp/aicontext/.github .    # GitHub Copilot
rm -rf /tmp/aicontext

Updating

aicontext update    # Update framework files (preserves your project-specific files)
aicontext upgrade   # Upgrade the CLI tool itself

For Teams

| Committed to git | Gitignored | |------------------|------------| | Rules, prompts, templates, specs, tasks | Task-contexts, reviews, PR drafts, personal settings |

Team members share the same rules and task history. Each person's task-contexts and preferences stay local. See project structure for details.

Customization

One config file controls how the AI works — no prompt engineering needed:

• Project settings: Edit .aicontext/config.yml (review/test/commit behavior, task naming, update checks)
• Personal overrides: Create .aicontext/config.local.yml (gitignored, overrides shared settings)
• Team rules: Edit .aicontext/project.md
• Personal rules: Edit .aicontext/local.md (gitignored)
• Remove unused tools: Delete .cursor/, .codex/, .github/, or .claude/ as needed

Learn More

• Development Model — how specs, tasks, task-contexts, and quality checks work together
• Workflow Guide — step-by-step guides for common workflows
• Skills Reference — detailed descriptions of every skill

Version History

| Version | Highlights | |---------|------------| | 1.12.0 | Native Pi skills (/skill:name). Worker orchestration with /orchestrate-workers. Separate task closure via /close-task and persistent task status. Bounded PR readiness with /gh-resolve-pr. Cached, silent update checks and on-demand config loading. | | 1.11.0 | OpenCode and Pi workflow support. Selective Codex skill routing. Explicit make-pr workflow, with draft-pr now local-only. Task and spec loading via load-task and load-spec. Typed response references for questions, concerns, risks, decisions, actions, unexpected findings, and options. | | 1.10.0 | Configurable TDD (tdd: true/false/ask). Dedicated plan-steps.md for plan-creation-time rules. Branch verification before remote ops. Correct git range operators in PR drafts. | | 1.9.0 | Documentation generation (/generate-docs). Type-aware test config with per-type scoping. Self-healing updates and --force flag. Choose which AI tools to install. Clearer skill names (/resume-task, /review-task). | | 1.8.0 | PR workflow automation — config guards, review-fix loop, resumable close. Project tidying (/tidy-aic). TDD-aware planning. "Brief" → "task-context" rename. Local version cache. ESM compatibility fix. | | 1.7.0 | Adaptive workflow — the AI learns your preferences and stops asking. GitHub issue creation. Thinking tools (/interview, /brainstorm, /thoughts). Automated CI fix (/gh-fix-tests). Ideas backlog. Smarter interviews that recommend answers. | | 1.6.0 | The big workflow release — three-layer context (spec/task/task-context), structured planning, automated execution with review and test loops, PR automation, browser inspection with /web-inspect. | | 1.5.0 | Codex support, /draft-issue, tool-agnostic PR scripts. | | 1.4.0 | Slash command skills, PR workflow scripts, agent model upgrades to sonnet/opus. | | 1.3.0 | Claude Code subagents — reviewer, researcher, test-runner working in parallel. | | 1.2.0 | Auto-update checking, aicontext upgrade, .ai/ → .aicontext/ rename. | | 1.0.0 | Initial release — rules, prompts, templates, multi-tool support. |

See CHANGELOG.md for full details.

License

MIT