AI Collaboration Framework

Installable internal framework for AI-driven projects that need shared rules, workflows, commands, gates, agents, skills, state, memory, and handoff conventions across Codex, Claude, Kimi, and other assistants.

Install Into A Project

From this package directory:

npm run ci
npm run validate
node bin/aif.js init /path/to/target-project

Then open:

onboarding.html

For a markdown quick reference, read:

ONBOARDING.md
USAGE.md

After publishing internally:

npx @iamohmcub/ai-framework init

Or install the Go CLI:

go install github.com/iamohmcub/ai-framework/cmd/aif@latest
aif init .

Commands

aif init [target] [--force] [--no-adapters]
aif update [target] [--force] [--no-adapters]
aif validate [target]
aif doctor [target]
aif list
aif workspace init [target]
aif workspace link <name> <repo-path> [--type service] [--provides api:x] [--consumes api:y]
aif workspace contract <id> --provider <repo> [--consumers web,mobile] [--spec path] [--spec-version v1] [--risk high] [--checks "contract tests,consumer review"] [--evidence commit-or-tag]
aif workspace status [target]
aif workspace impact <source-repo> <contract-id> [target] [--write-handoffs] [--from ref] [--to ref]
aif workspace release <name> [target] [--repos backend,frontend] [--since "2 weeks ago"]
aif workspace doctor [target]
aif git snapshot [target] [--name milestone-name]
aif git logbook [target] [--since "2 weeks ago"]
aif git trace <commit-or-file> [target]
aif git milestone <name> [target]

The Go CLI currently supports install/update/validate/doctor/list and workspace init/status/doctor. The npm CLI remains the full-featured reference for workspace impact, release, and git evidence commands.

What Gets Installed

• .ai/core/: protocol, constitution, governance principles, handoff, memory, quality bar
• .ai/governance/: internal AI policy and source mapping
• .ai/git/: Git Evidence Spine policies for commit, branch, tag, release, PR, logs, and milestones
• .ai/schemas/: stable production schema contracts
• .ai/gates/: risk screen, review, tests, integration, full verification
• .ai/workflows/: universal and main team workflows
• .ai/commands/: AI-neutral command cards such as /plan, /build, /wrap-up
• .ai/rules/: engineering, product, security, privacy, data, design, documentation
• .ai/rules/go.md: Go-specific project and CLI rules
• .ai/agents/, .ai/roles/, .ai/skills/: reusable role and task definitions
• .ai/templates/: standard artifacts and responses
• .ai/state/: operational state files
• .ai/memory/: decisions and handoffs
• AGENTS.md, CLAUDE.md, KIMI.md, GEMINI.md, CURSOR.md, WINDSURF.md, COPILOT.md, AIDER.md, GENERIC_AI.md: tool adapters
• onboarding.html: interactive onboarding guide for workflows, commands, gates, state, and handoff

Update Existing Projects

npx @iamohmcub/ai-framework update
npx @iamohmcub/ai-framework doctor

update protects project-specific continuity folders by default:

.ai/project/
.ai/state/
.ai/memory/

Use --force only when you intentionally want to overwrite existing framework files.

Internal Usage Model

Tool adapter
  -> .ai/core/protocol.md
  -> .ai/governance/policy.md
  -> .ai/commands or workflows
  -> .ai/rules + gates
  -> .ai/state + memory

Design Principle

Adapters are doorways. .ai/ is the source of truth.

Keep universal rules in this package. Put project-specific context in .ai/project/ after installation.

Multi-Repo Workspace

For a full real-world example, read USAGE.md.

For ecosystems with backend, frontend, mobile, data, or infrastructure repos, initialize a shared workspace next to the repos:

aif workspace init .
aif workspace link backend ../backend --type service --provides api:user,event:user.updated
aif workspace link frontend ../frontend --type web --consumes api:user
aif workspace link mobile ../mobile --type app --consumes api:user,event:user.updated
aif workspace contract api:user --provider backend --consumers frontend,mobile --spec ../backend/openapi.yaml --spec-version v1 --risk high --checks "contract tests,consumer review" --evidence v1.2.0
aif workspace status
aif workspace impact backend api:user --write-handoffs --from v1.1.0 --to HEAD
aif workspace release v1.2.0 --repos backend,frontend,mobile --since "2 weeks ago"

Workspace files live in:

.aif-workspace/

This layer is intentionally separate from per-repo .ai/ folders. It coordinates cross-repo contracts, ownership, impact reports, and handoffs without making one repo the source of truth for all others.

Reports, Logs, And Handoffs

Per-repo operating state lives in each repo:

.ai/state/session-log.md
.ai/state/work-streams.md
.ai/state/problem-tracker.md
.ai/memory/handoffs/
.ai/memory/decisions/

Cross-repo coordination evidence lives in the workspace:

.aif-workspace/reports/
.aif-workspace/handoffs/

Use reports for cross-repo impact analysis, contract changes, release coordination, and incident follow-up. Use handoffs when another repo owner or AI assistant needs to continue the work.

When --write-handoffs is used, AIF writes handoff files into each affected consumer repo:

frontend/.ai/memory/handoffs/YYYY-MM-DD-backend-api-user-impact.md
mobile/.ai/memory/handoffs/YYYY-MM-DD-backend-api-user-impact.md

Git Evidence Spine

Use Git as the durable ledger for AI-driven work:

aif git snapshot --name feature-checkpoint
aif git logbook --since "2 weeks ago"
aif git trace README.md
aif git milestone v0.3

Generated evidence lives in:

.ai/state/git-logbook.md
.ai/memory/git-snapshots/
.ai/memory/git-traces/
.ai/memory/milestones/

Use these artifacts to connect commits, PRs, releases, workspace reports, and handoffs.

Workspace Evidence Integration

Workspace reports can now pull git evidence from linked repos and attach contract version references:

aif workspace contract api:user --provider backend --consumers frontend,mobile --spec-version v1 --evidence v1.2.0
aif workspace impact backend api:user --from v1.1.0 --to HEAD --write-handoffs
aif workspace release v1.2.0 --repos backend,frontend,mobile --since "2 weeks ago"

Use this when a backend contract change should produce frontend/mobile handoffs with commit context, or when a release needs one bundle of repo state, commits, contracts, and next checks.

Versioning And Updates

Package versioning follows semantic versioning:

• PATCH: docs, small fixes, non-breaking template updates
• MINOR: new commands, workflows, adapters, compatible workspace/evidence features, or workspace evidence integration
• MAJOR: breaking layout or command behavior

Before publishing:

npm run ci
npm run pack:dry

Then:

npm version patch
npm publish --access public

Use npm publish --access restricted only for private npm distribution.

Installed projects update with:

npx @iamohmcub/ai-framework update

update preserves project continuity folders by default:

.ai/project/
.ai/state/
.ai/memory/

See VERSIONING.md for the full policy.

Production Readiness

1.0.0 is the stable production baseline.

Use:

npm run ci

This validates the framework, workspace registry, Node smoke flow, Go tests, Go binary smoke flow, and npm package contents.

Upgrade existing projects with MIGRATION.md. Release using RELEASE.md.

Go Module

Read GO.md for Go installation and development details.

go test ./...
go run ./cmd/aif validate .

v1.0 criteria are tracked in ROADMAP.md and are complete for this baseline.