AI Co-Working Kit v2.3

AI-assisted project operating standard for structure, coding standards, contracts, governance, quality, delivery, and tool integration.

The package version (this file's title) and the contract/frontmatter format version are tracked separately: this release is 2.3.0, but feature/migration/release contracts still use the "v2.2" frontmatter format (schemaVersion: 2) — no forced ai-kit upgrade migration is required.

Mental Model

src/          BUILD
standards/    CODE QUALITY
docs/         UNDERSTAND
references/   LOOK AT
.ai/          REMEMBER / GOVERN
.agents/      HOW AI WORKS
deploy/       SHIP
scripts/      AUTOMATE
configs/      CONFIGURE

1. Structure

Canonical active-source model:

src/
├── apps/
├── features/
├── core/
├── platform/
└── bootstrap/

Not every project needs every subfolder. Strict physical enforcement is configurable.

2. Coding Standards

standards/
├── general.md
├── go.md
├── typescript.md
├── python.md
├── sql.md
└── security.md

Active standards are declared in .ai/config.json.

Technical naming defaults to English. Documentation languages are configurable.

3. Structured Contracts

Feature and migration contracts use versioned frontmatter for machine state and Markdown for reasoning/evidence.

Example feature metadata:

---
kind: feature
schemaVersion: 2
name: coding-workspace
status: planning
priority: P1
owner: ryan
risk: high
executionMode: 2
dependsOn: [coding-projects]
securityImpact: [filesystem, process, external-input]
requiredReviews: [feature, security]
approvalBy: ""
approvalAt: ""
reviewVerdict: pending
---

4. Feature Lifecycle

planning
→ awaiting-approval
→ approved
→ in-progress
→ review
   ├→ done
   └→ changes-required → rework → review

Commands:

ai-kit feature coding-workspace --owner ryan --risk high --depends coding-projects --depends-migrations coding-registry
ai-kit prompt plan coding-workspace
ai-kit validate coding-workspace
ai-kit approve coding-workspace --by ryan
ai-kit start coding-workspace
ai-kit prompt implement coding-workspace
ai-kit review coding-workspace --type security --verdict ready
ai-kit review coding-workspace --verdict ready
ai-kit done coding-workspace

approve/review/finding add only run from the correct current status (e.g. approve requires planning/awaiting-approval; review/finding add require approved or later) — calling them out of order fails fast with a clear error instead of silently corrupting contract state.

done enforces:

• approved/real owner metadata
• dependencies done (features and migrations — see dependsOnMigrations below)
• all ACs checked
• review verdict ready
• all required reviews passed
• no open critical/high findings

A feature contract may declare dependsOnMigrations: [<migration-name>, ...] (or --depends-migrations a,b at creation). approve and done are blocked until every listed migration reaches done.

5. Review / Rework

Machine-readable review state lives in:

.ai/features/<feature>/review.json

Findings:

ai-kit finding add coding-workspace --severity HIGH --text "Unsafe path authorization order"
ai-kit finding resolve coding-workspace RF-001
ai-kit rework coding-workspace

6. Risk / Required Reviews

Supported review types:

• feature
• security
• database
• architecture
• deployment

Security-sensitive contract metadata automatically validates that a security review is required. Database and deployment impacts receive the same treatment.

7. Migration Lifecycle

planning
→ awaiting-approval
→ approved
→ in-progress
→ review
   ├→ done → archived
   └→ changes-required → rework → review

ai-kit migration create coding-registry --type database --change-class minor
ai-kit prompt migration-plan coding-registry
ai-kit migration approve coding-registry --by ryan   # skipped automatically for safe/minor if policy allows
ai-kit migration start coding-registry
ai-kit prompt migration-apply coding-registry
ai-kit prompt migration-review coding-registry
ai-kit migration review coding-registry --verdict ready
ai-kit migration done coding-registry
ai-kit migration archive coding-registry

Feature planners detect migration needs but should not create migration workspaces manually. Use the CLI lifecycle.

Every migration has a changeClass (safe/minor/major, default minor, set via --change-class). ai-kit migration start reads .ai/config.json → migrations.defaultApprovalPolicy for that class: safe/minor (policy auto/auto-log-verify) may start directly from planning; major (policy human) still requires ai-kit migration approve first.

7b. Release Lifecycle

planning → approved → in-progress → review → done → archived
                              ↑          ↓
                              └─ changes-required

ai-kit release create web-2026-09 --env production
ai-kit prompt release-plan web-2026-09
ai-kit release approve web-2026-09 --by ryan   # skipped automatically if the environment's approvalRequired is false
ai-kit prompt deploy-plan web-2026-09
ai-kit release deploy web-2026-09
ai-kit prompt post-deploy-check web-2026-09
ai-kit release review web-2026-09 --verdict ready
ai-kit release done web-2026-09
ai-kit release archive web-2026-09

Release workspaces live under .ai/releases/active|archive/<name>/RELEASE.md + review.json, following the same contract shape as features/migrations. ai-kit release deploy reads .ai/config.json → deployment.environments.<env>.approvalRequired (falling back to deployment.productionApprovalRequired for production) to decide whether it may run directly from planning or requires ai-kit release approve first.

8. Verification Classification

Verification results distinguish:

PASS
FAIL_INTRODUCED
FAIL_BASELINE
FAIL_ENVIRONMENT   # recorded in contract/review evidence when environment-specific
SKIPPED

Known command-level baselines may be configured in .ai/config.json so an unchanged known failure is not confused with a new regression.

9. JSON CLI

Stable machine-readable envelopes are available for tool integration such as Taurin:

ai-kit status --json
ai-kit doctor --json
ai-kit feature show coding-workspace --json
ai-kit migration list --json
ai-kit migration show coding-registry --json
ai-kit release list --json
ai-kit release show web-2026-09 --json
ai-kit verify full --json
ai-kit reference list --json

--json output is compact single-line JSON (not pretty-printed) since it is the machine/AI integration surface, not a human-formatted view.

Envelope:

{
  "schemaVersion": 1,
  "command": "status",
  "ok": true,
  "data": {}
}

10. Upgrade from v2.1

In an existing project:

ai-kit upgrade
ai-kit prompt upgrade-project
ai-kit doctor

upgrade safely:

• merges config to schemaVersion 3
• converts legacy feature/migration metadata to v2.2 frontmatter
• creates review.json files
• installs/updates standards and agent skills
• syncs thin adapters

It does not overwrite project-specific AGENTS.md or human docs. Use prompt upgrade-project to reconcile those with repository evidence.

11. Install / Development with pnpm

pnpm install
pnpm test
pnpm run lint
pnpm run format        # pnpm run format:check to verify without writing
pnpm run verify         # syntax-check + lint + format:check + tests
npm link                # exposes `ai-kit` globally; more reliable than `pnpm link --global`,
                         # which needs `pnpm setup` + a shell restart on some Windows setups
ai-kit version

CI runs pnpm run verify on every push/PR across Node 18/20/22 (see .github/workflows/ci.yml).

12. Deployment / References / Operations

v2.2 retains v2.1 zones and governance for:

• references/legacy, themes, examples, API samples, vendor docs
• .ai/migrations/
• .ai/DEPLOYMENT.md
• .ai/OPERATIONS.md
• .ai/SECURITY.md
• deploy/, scripts/, configs/
• production human approval by default

13. Marketing / Docs Website

A standalone static site (install + usage guide) lives in website/, deployed to Cloudflare Workers as static assets — no build step, no runtime dependency on the CLI package. See website/README.md; preview locally with website/dev.ps1/dev.sh (no Cloudflare login needed, no npm publish).

npm is the single install source the site documents (npm install -g ai-co-working-kit). website/deploy.ps1/deploy.sh therefore also publish the CLI to npm (via scripts/publish.ps1/publish.sh, §14) before deploying the site, so one command ships both. Pass -SkipPublish (PowerShell) / --skip-publish (bash) to redeploy only the website (e.g. a docs-only fix) without cutting a new npm release.

14. Publishing to npm

Maintainer-only. npm publish needs an authenticated npm account — there is no way to fully automate that away (npm doesn't support username/password login for scripts, only per-account access tokens), so the one-time setup is:

1. On npmjs.com → avatar → Access Tokens → Generate New Token → type Automation (doesn't prompt for OTP on every publish) → permission Read and write packages.
2. Copy .npmrc.publish.example → .npmrc.publish (repo root) and paste the token into it. This file is gitignored — it never gets committed.

From then on, every release is one command:

.\scripts\publish.ps1        # Windows

./scripts/publish.sh         # macOS/Linux/WSL/Git Bash

Each run automatically:

• authenticates using the token in .npmrc.publish (without touching your global ~/.npmrc)
• checks whether package.json's current version is already published; if so, bumps the patch version and keeps src/util.js / test/cli.test.js in sync — if not, publishes that version as-is (so the version bump you already committed is respected)
• runs pnpm run verify and npm publish --dry-run (aborting on any failure or on the exact bin warning that previously would have shipped a broken package) before ever publishing for real

Add -DryRun (PowerShell) / --dry-run (bash) to run every check without actually publishing. After a successful publish, commit the version-bump files and tag the release (the script prints the exact commands).