aikko

A framework of rules and conventions that makes Cursor AI a disciplined, structured engineering partner — in any project, any stack.

Drop the files into a project and Cursor follows the system automatically.

What it does

aikko defines a three-phase workflow for AI-assisted development:

| Phase | What happens | |---|---| | Plan | Restate task, list files, number steps, confirm if significant | | Build | Execute step by step with progress reports | | Verify | Lint, test, diff, debug-output check, DoD checklist |

Plus guardrails (git safety, no secrets, no scope creep, no OWASP), code standards, design system rules, and project onboarding.

Installation

Option 1: copy into a project

cp .cursorrules /path/to/your-project/
cp AGENTS.md /path/to/your-project/
cp CLAUDE.md /path/to/your-project/
cp -r aikko /path/to/your-project/aikko
cp -r docs /path/to/your-project/docs

Cursor reads .cursorrules automatically.

Option 2: git subtree

git subtree add \
  --prefix=aikko-framework \
  https://github.com/altegodigital/aikko.git \
  master --squash

Option 3: use as GitHub template

Click "Use this template" on GitHub.

First run

Start a Cursor session and type anything. aikko detects whether your project is new or existing:

• Existing project (has package.json etc.) → aikko scans your files and auto-generates project context. One confirmation question.
• New project (empty directory) → short structured Q&A to establish context.

Project context is saved to .aikko-tasks/PROJECT.md and read every session.

File structure

.cursorrules              ← Core rules. Self-contained (~225 lines).
aikko/
  details.md              ← Expanded specs (code standards, git, design, perf, ADR, templates).
  onboarding.md           ← Project onboarding protocol.
AGENTS.md                 ← AI governance policy.
CLAUDE.md                 ← AI assistant guidance.
bin/
  aikko.js                ← CLI (npx aikko init).
  aikko-verify.js         ← Pre-commit verification.
docs/
  COMPONENTS.md           ← Component inventory (UI projects).
  decisions/              ← Architecture Decision Records.

How to use it

Once installed, Cursor follows the rules automatically. You interact normally.

"Add user authentication to this API."
→ aikko plans, confirms, implements step by step, verifies.

"The JWT validation is failing. Debug it."
→ aikko reproduces, diagnoses root cause, fixes, writes regression test.

"Review the auth implementation."
→ aikko lists issues by severity with file/line references.

Customising

| What | Where | |---|---| | Code standards | aikko/details.md §1 | | Git workflow | aikko/details.md §4 | | Design system | aikko/details.md §5 | | Performance budget | aikko/details.md §6 — or override in PROJECT.md | | Task templates | aikko/details.md §3 | | Definition of Done | .cursorrules §5 |

v1 → v2 changes

| v1 | v2 | |---|---| | 7 agent roles (Orchestrator, Planner, Coder, Tester, Critic, Debugger, Documenter) | 3 phases (Plan, Build, Verify) | | 20 markdown files | 4 core files | | .aikko-tasks/TASK-NNN/ with subtask trees | Single active.md file | | 10-question onboarding for every project | Quick-start auto-detection for existing projects | | @-references to external files | Self-contained .cursorrules | | ~2500 lines of instructions | ~1000 lines total |

Design principles

1. Less is more. Fewer rules = higher compliance.
2. Self-contained. .cursorrules works without loading external files.
3. Verifiable. DoD includes concrete commands, not abstract checklists.
4. Honest about LLMs. One model, three phases — not seven pretend agents.
5. Minimal overhead. Task state is one file, not a directory tree.

Contributing

See AGENTS.md for governance and CLAUDE.md for git conventions.