AI Core Framework

AI Core is a chat-first Agile workflow framework for AI coding agents. It installs agents, rules, skills, templates, workflows, scripts, and governance checks into a project so agents can move work through a controlled ticket lifecycle.

Install

Run from the target project root:

npx ai-core-framework

The installer asks which AI CLI to target. Version 0.1 supports Codex and copies root-level framework folders into .codex/:

.codex/
  agents/
  docs/config/
  rules/
  scripts/
  skills/
  templates/
  workflows/
  README.md

If a destination file exists, choose overwrite, skip, or cancel. Pressing Enter skips.

Use When

• You want AI agents to run a ticket-based workflow instead of ad hoc coding.
• You need explicit role boundaries between BA, Tech Lead, Developer, QA, and Scrum Master.
• You want state validation, documentation gates, audit logs, request logs, and generated status views.
• You want chat commands such as /analyze-requirements, /groom-ticket, /daily-standup, /implement-task, and /smoke-test.

Do Not Use When

• You want a lightweight prompt collection with no state machine.
• You do not want tickets, governance files, or role-based command ownership.
• You need the user to manually drive shell scripts for every step. AI Core is chat-first.

Iron Law

Root-level framework folders are the source of truth. Generated platform files are outputs. Edit the source folders, then run /sync-platforms when platform config must be regenerated.

Normal Chat Flow

/setup-project
/document-architecture
/validate-state
/validate-docs
/validate-permissions
/generate-views
/analyze-requirements "User can reset password"

Guided mode:

guide /analyze-requirements "User can reset password"
next TICKET-001

Agents should infer the correct role from command metadata and may use scripts/ai-core.sh internally. Users should not need to type shell wrappers for normal workflow actions.

State Path

DRAFT -> GROOMED -> READY -> IN_PROGRESS -> IN_REVIEW -> QA -> DONE
                                |
                                v
                             BLOCKED

Every transition is governed by command skills, rules, and validation scripts.

Core Commands

• /setup-project: scaffold project config, runtime folders, architecture docs, and conventions docs.
• /document-architecture: document actual architecture and coding conventions from repository evidence.
• /analyze-requirements: create a DRAFT ticket from stakeholder input.
• /write-user-story: refine an INVEST-compliant user story.
• /create-acceptance-criteria: create testable Gherkin acceptance criteria.
• /document-existing-requirements: document current behavior from source evidence.
• /groom-ticket: refine and estimate a DRAFT ticket.
• /dependency-map: inspect dependency ordering, blockers, and critical-path risk.
• /create-adr: record architecture decisions required by tickets or reviews.
• /write-plan: create and link an implementation plan.
• /mark-ready: move eligible work to READY.
• /daily-standup: report active sprint health, blockers, aging work, and next actions.
• /retrospective: close sprint learning and track improvement actions as tickets.
• /implement-task: implement READY or IN_PROGRESS work with TDD.
• /write-unit-tests: add ticket-scoped unit or regression tests.
• /refactor: perform bounded behavior-preserving refactors.
• /run-tests: execute project tests and report fresh evidence.
• /check-coverage: verify diff and overall coverage against quality gates.
• /sync-branch: synchronize a work branch with its target branch safely.
• /create-pr: prepare review after implementation gates pass.
• /techlead-review: review architecture, security, tests, docs, and maintainability.
• /security-review: perform focused security review for risky changes.
• /request-changes: send review work back with evidence-based required fixes.
• /merge-pr: merge approved work and move the ticket to QA.
• /smoke-test: verify deployed work and move QA work to DONE when evidence passes.
• /unblock: verify blocker resolution and return a ticket to its previous valid state.
• /release: validate and record a release.
• /rollback: plan or execute rollback with evidence.

Mechanical Gates

• scripts/validate-state.sh: state transitions, backlog ordering, blocked tickets, DoD fields, QA evidence, and release governance.
• scripts/validate-docs.sh: documentation obligations from diffs and ticket metadata.
• scripts/validate-permissions.sh: command ownership and self-approval checks.
• scripts/validate-audit-log.sh: audit log hash-chain integrity.
• scripts/log-user-request.sh: append-only user request log.
• scripts/generate-views.sh: dashboards and release readiness views.

Red Flags

• Asking users to run internal shell commands for normal chat workflow.
• Editing generated platform files instead of root-level source folders.
• Moving tickets by hand without the matching command.
• Claiming DONE without QA evidence and DoD fields.
• Treating documentation gates as optional after code changes.