@camilyos/codex-antigravity-kit 0.1.0

package/AGENTS.md

@@ -0,0 +1,13 @@
+# Codex Runtime Contract
+
+Codex role: Technical Lead, Architect, Planner, Orchestrator, Reviewer, Verifier.
+
+Execution order:
+Understand -> Inspect -> Clarify -> Brainstorm -> Plan -> Delegate -> Review -> Repair -> Verify -> Complete.
+
+Rules:
+1. Search before asking.
+2. If missing context affects architecture/behavior/security/compatibility, stop and ask.
+3. Do not invent requirements.
+4. Do not delegate before task spec is complete.
+5. PASS only after verification and independent review.

package/README.md

@@ -0,0 +1,234 @@
+# Codex Antigravity Kit
+
+A production-focused orchestration kit where:
+
+- Codex is the brain (clarification, planning, review, verification).
+- Antigravity (`agy`) is the implementation worker.
+- Codex agents and skills live under `.codex/agents` and `.codex/skills`.
+- Brainstorming and planning have their own Codex agent/skill templates.
+- Durable artifacts are stored in `.agent-workflow`.
+- Repair loops are tracked until PASS or escalation.
+
+## Install
+
+Run via npx:
+
+```bash
+npx @camilyos/codex-antigravity-kit init
+```
+
+Or install globally:
+
+```bash
+npm i -g @camilyos/codex-antigravity-kit
+codex-antigravity-kit --help
+```
+
+## NPM Publish (public org)
+
+Package is configured for public scoped publish:
+
+- name: `@camilyos/codex-antigravity-kit`
+- `publishConfig.access = public`
+- dual module output (ESM + CJS)
+
+Publish steps:
+
+```bash
+npm run test
+npm run build
+npm publish --access public
+```
+
+## Commands
+
+### GSD-style output flow
+
+```bash
+# 1. Brainstorm context, options, and constraints into BRAINSTORM.md
+codex-antigravity-kit brainstorm --task TEST-01 --spec ./tasks/TEST-01-SPEC.md
+
+# 2. Plan phases, tasks, and acceptance criteria into PLAN.md
+codex-antigravity-kit plan --task TEST-01
+
+# 3. Execute directly runs the worker on the context described in PLAN.md (auto-detects agent)
+codex-antigravity-kit execute --task TEST-01
+
+# (Optional) Explicitly select an agent or pass a custom context file:
+codex-antigravity-kit execute --task TEST-01 --agent web-engineer
+codex-antigravity-kit execute --task TEST-01 --file ./tasks/CUSTOM-CONTEXT.md
+```
+
+### Smart Agent Routing
+
+The kit automatically inspects task specifications, keywords, and repository indicators to assign the most appropriate specialized agent and skill practices:
+- **`web-engineer`**: React, Next.js, Vue, REST/GraphQL, Tailwind, CSS, DOM, CWV.
+- **`mobile-engineer`**: Flutter, React Native, iOS Swift/SwiftUI, Android Kotlin/Compose, SQLite.
+- **`game-engineer`**: Unity C#, Godot GDScript/C#, Cocos Creator TypeScript, Physics, RigidBody, FPS.
+- **`researcher`**: Technical spikes, feasibility studies, library benchmarking, PoC analysis.
+- **`business-analyst`**: Requirements elicitation, user stories, Gherkin Given/When/Then scenarios.
+- **`codex`**: General technical lead & architecture fallback.
+
+Override auto-detection anytime via `--agent <name>`.
+
+These commands generate the durable artifacts that mirror the GSD-style workflow:
+
+- `BRAINSTORM.md` (Problem framing, context, options, risks)
+- `PLAN.md` (Actionable phases, scope, acceptance criteria)
+- `EXECUTE.md` & `RESULT.md` (Execution package and worker implementation result)
+
+### 1) Initialize kit
+
+```bash
+codex-antigravity-kit init
+```
+
+Creates:
+
+- `AGENTS.md`
+- **Agents (`.codex/agents/`)**:
+  - `codex.md` (Tech lead & orchestrator)
+  - `brainstormer.md` (Problem framing & discovery)
+  - `planner.md` (Phases, tasks, and acceptance criteria)
+  - `researcher.md` (Deep technical spikes, benchmarks & feasibility)
+  - `business-analyst.md` (Requirements elicitation, user stories & Gherkin AC)
+  - `web-engineer.md` (Fullstack web, responsive UI, APIs & performance)
+  - `mobile-engineer.md` (iOS Swift, Android Kotlin, React Native, Flutter)
+  - `game-engineer.md` (Unity C#, Godot GDScript/C#, Cocos Creator TypeScript)
+- **Skills (`.codex/skills/`)**:
+  - `codex-workflow.md` (Core orchestration flow)
+  - `brainstorming.md` (Decision framing & options evaluation)
+  - `planning.md` (Task breakdown & execution handoff)
+  - `research.md` (Spike analysis & architectural comparison)
+  - `requirements-analysis.md` (Domain modeling & Gherkin specifications)
+  - `web-engineering.md` (Component hierarchy, state flow & API contracts)
+  - `mobile-engineering.md` (Navigation, offline storage & native bridges)
+  - `game-engineering.md` (Game loops, physics layers & performance profiling)
+- `.antigravity/WORKER_RULES.md`
+- `.agent-workflow/PROJECT.md`
+- `.agent-workflow/ARCHITECTURE.md`
+- `.agent-workflow/DECISIONS.md`
+- `.agent-workflow/STATE.md`
+- `.agent-workflow/config.json`
+
+### 2) Doctor
+
+```bash
+codex-antigravity-kit doctor
+```
+
+Checks:
+
+- `agy` availability
+- workflow files present
+- config present
+
+### 3) Status
+
+```bash
+codex-antigravity-kit status
+```
+
+Shows workflow state snapshot.
+
+### 4) Delegate implementation
+
+```bash
+codex-antigravity-kit delegate \
+  --task AUTH-03 \
+  --spec ./tasks/AUTH-03-SPEC.md \
+  --timeout-ms 600000
+```
+
+Optional repair request:
+
+```bash
+codex-antigravity-kit delegate \
+  --task AUTH-03 \
+  --spec ./tasks/AUTH-03-SPEC.md \
+  --repair-request ./tasks/AUTH-03-REPAIR.md
+```
+
+### 5) Record review outcome
+
+```bash
+codex-antigravity-kit review --task AUTH-03 --outcome FAIL
+codex-antigravity-kit review --task AUTH-03 --outcome PASS
+```
+
+## Workflow Artifacts
+
+Per task artifacts are stored under:
+
+```text
+.agent-workflow/tasks/<task-id>/
+  SPEC.md
+  REPAIR_REQUEST.md (optional)
+  RESULT.md
+  REVIEW.md
+```
+
+State snapshot:
+
+- `.agent-workflow/STATE.md`
+
+## State Machine
+
+- `IDLE -> DISCOVERY -> BRAINSTORMING -> PLANNING -> READY -> IMPLEMENTING -> VERIFYING -> REVIEWING`
+- `REVIEWING -> COMPLETED` (PASS)
+- `REVIEWING -> REPAIR_REQUIRED -> IMPLEMENTING` (FAIL)
+- `REVIEWING/BLOCKED -> ESCALATION_REQUIRED` (BLOCKED or limits)
+
+## Recovery
+
+Workflow can recover after interruption by reading:
+
+- `.codex/agents/codex.md`
+- `.codex/skills/codex-workflow.md`
+- `.agent-workflow/STATE.md`
+- latest task artifacts under `.agent-workflow/tasks`
+
+## Codex Agent And Skill Layer
+
+Use the scaffold when you want Codex to work with named roles and reusable skills.
+
+- Put agent definitions in `.codex/agents/*.md`
+- Put reusable workflow skills in `.codex/skills/*.md`
+- Keep `AGENTS.md` as the top-level runtime contract
+- Use `doctor` to verify the scaffold exists before running tasks
+
+Recommended usage for GSD-style work:
+
+1. `brainstormer` reads the request and writes the problem framing.
+2. `planner` turns the framing into phases, tasks, and acceptance criteria.
+3. `codex-workflow` keeps the whole flow consistent with `brainstorm -> plan -> execute -> delegate -> review`.
+
+The starter files created by `init` are intentionally small so you can rename or extend them to fit your own Codex workflow.
+
+## Testing
+
+```bash
+npm test
+```
+
+Covers:
+
+- transition validation
+- repair loop limits
+- result parsing
+- state persistence
+
+## Example End-to-End
+
+1. Codex writes task spec to `AUTH-03-SPEC.md`.
+2. Run delegate.
+3. Worker writes result.
+4. Codex reviews and records FAIL.
+5. Codex writes repair request and delegates again.
+6. Codex records PASS.
+
+## Known Limitations
+
+- This version does not auto-generate review findings; review authoring remains explicit.
+- Worker result parsing is contract-driven and expects `DONE | BLOCKED | FAILED` in output.
+- Integration simulation with real code edits depends on target repository and task specs.