Initial commit: antigravity-claudekit

skills/ck-orchestration/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: ck-orchestration
+description: Orchestrate multi-agent workflows with sequential chaining and parallel execution. Use for feature delivery pipelines, research-then-implement flows, parallel independent tasks, subagent coordination, and passing context between agents.
+---
+
+# ck-orchestration
+
+Protocols for coordinating multiple ck-* skills as agents in complex workflows. Covers sequential chaining, parallel execution, delegation patterns, and documentation management.
+
+## When to Use
+
+- Coordinating a multi-phase feature delivery (plan → implement → test → review)
+- Running independent tasks simultaneously (code + tests + docs in parallel)
+- Passing outputs from one agent to the next in a pipeline
+- Managing subagent context and report paths
+- Deciding when to chain vs. parallelize work
+
+## Don't Use When
+
+- Single-skill tasks that don't need coordination
+- Quick fixes or one-off queries — invoke the skill directly
+
+## Reference Documents
+
+| Topic | Reference |
+|-------|-----------|
+| Sequential chaining patterns | `references/sequential-chaining.md` |
+| Parallel execution patterns | `references/parallel-execution.md` |
+| Delegation context rules | `references/delegation-context.md` |
+| Documentation management | `references/documentation-management.md` |
+
+---
+
+## Sequential Chaining
+
+Chain agents when tasks have dependencies or require outputs from previous steps.
+
+**Standard feature pipeline:**
+```
+ck-planning → ck-cook → ck-web-testing → ck-code-review
+```
+
+**Research-first pipeline:**
+```
+ck-research → ck-planning → ck-cook → ck-code-review
+```
+
+**Debug pipeline:**
+```
+ck-debug → ck-fix → ck-web-testing → ck-code-review
+```
+
+**Rules:**
+- Each agent completes fully before the next begins
+- Pass the output file path (plan path, report path) as context to the next agent
+- Never assume an agent's output — read it explicitly before proceeding
+
+See `references/sequential-chaining.md` for detailed patterns.
+
+---
+
+## Parallel Execution
+
+Dispatch multiple agents simultaneously for independent tasks.
+
+**When to parallelize:**
+- Code + Tests + Docs: implementing separate, non-conflicting components
+- Multiple feature branches: different agents on isolated features
+- Research fan-out: multiple `ck-research` agents on different topics reporting back to `ck-planning`
+- Scout coverage: multiple `ck-scout` agents covering different directories
+
+**When NOT to parallelize:**
+- Tasks that write to the same files
+- Tasks where one depends on output of another
+- More than the available system resources can handle
+
+**Coordination rule:** Define integration points before starting parallel execution. Plan how results will be merged.
+
+See `references/parallel-execution.md` for patterns.
+
+---
+
+## Delegation Context (MANDATORY)
+
+When dispatching any subagent via the Manager Surface, always include:
+
+1. **Work Context Path**: The git root or CWD of the PRIMARY files being worked on
+2. **Reports Path**: `{work_context}/plans/reports/` for that project
+3. **Plans Path**: `{work_context}/plans/` for that project
+
+**Example prompt to subagent:**
+```
+Fix the parser bug in the auth module.
+Work context: /path/to/project
+Reports: /path/to/project/plans/reports/
+Plans: /path/to/project/plans/
+```
+
+**Rule:** If your CWD differs from the work context (e.g., editing files in a different project), use the **work context paths**, not CWD paths.
+
+See `references/delegation-context.md` for full rules.
+
+---
+
+## Skill Activation in Workflows
+
+Each ck-* skill maps to a workflow role:
+
+| Workflow Role | Use Skill |
+|---------------|-----------|
+| Research | `ck-research` (dispatch multiple in parallel) |
+| Codebase scouting | `ck-scout` |
+| Planning | `ck-planning` |
+| Implementation | `ck-cook` |
+| UI/design | `ck-frontend-design` |
+| Testing | `ck-web-testing` |
+| Code review | `ck-code-review` |
+| Debugging | `ck-debug` |
+| Bug fixing | `ck-fix` |
+| Git operations | `ck-git` |
+| Docs update | handled inline per `references/documentation-management.md` |
+
+---
+
+## Documentation Management
+
+Update project docs in `./docs` after:
+- Feature implementation
+- Bug fixes
+- Architecture changes
+- Security updates
+
+**Docs to maintain:**
+- `./docs/codebase-summary.md` — project structure overview
+- `./docs/system-architecture.md` — architecture decisions
+- `./docs/code-standards.md` — coding conventions
+- `./docs/development-roadmap.md` — phases and milestones
+- `./docs/project-changelog.md` — significant changes
+
+See `references/documentation-management.md` for update protocol.
+
+---
+
+## Report Naming Convention
+
+All agents write reports using the pattern from the `## Naming` section injected by `ck-session-guard`:
+
+```
+Report: {reports-path}/{agent-type}-{name-pattern}.md
+Plan dir: {plans-path}/{name-pattern}/
+```
+
+Where `{name-pattern}` is the computed date + optional issue ID + `{slug}` placeholder.
+
+**IMPORTANT:** Sacrifice grammar for concision in reports. List unresolved questions at end if any.

skills/ck-orchestration/references/delegation-context.md

@@ -0,0 +1,115 @@
+# Delegation Context Rules
+
+When dispatching any subagent via the Manager Surface, context must be passed explicitly. Subagents do not automatically inherit the parent's working directory or plan state.
+
+## Mandatory Context Fields
+
+Every subagent dispatch MUST include:
+
+| Field | Value | Purpose |
+|-------|-------|---------|
+| **Work Context Path** | Git root or CWD of primary files | Anchors all relative paths |
+| **Reports Path** | `{work_context}/plans/reports/` | Where subagent writes its report |
+| **Plans Path** | `{work_context}/plans/` | Where plans are located |
+
+**Example dispatch prompt:**
+```
+Fix the authentication bug in the login module.
+
+Work context: /home/user/projects/my-app
+Reports: /home/user/projects/my-app/plans/reports/
+Plans: /home/user/projects/my-app/plans/
+```
+
+## CWD vs Work Context
+
+The most common delegation mistake: using your current working directory when the work is in a different project.
+
+**Scenario:** Orchestrator is running from `/home/user/orchestrator/`, editing files in `/home/user/projects/my-app/`.
+
+```
+WRONG: Reports → /home/user/orchestrator/plans/reports/
+RIGHT: Reports → /home/user/projects/my-app/plans/reports/
+```
+
+**Rule:** Always use the **work context paths** (where the files live), not CWD paths.
+
+## Active Plan Passing
+
+If an active plan exists, include it in the subagent dispatch:
+
+```
+Implement phase-02 of the authentication plan.
+
+Plan file: /home/user/projects/my-app/plans/260101-1200-auth/phase-02-api.md
+Work context: /home/user/projects/my-app
+Reports: /home/user/projects/my-app/plans/260101-1200-auth/reports/
+Plans: /home/user/projects/my-app/plans/
+```
+
+Note: when an active plan exists, reports go to the **plan-specific** reports folder, not the default `plans/reports/`.
+
+## Agent-Type Specific Context
+
+Some agents need additional context beyond the standard fields:
+
+### ck-planning dispatch
+```
+Research these topics and create an implementation plan.
+
+Research reports available:
+- /path/to/reports/researcher-260101-1200-auth-patterns.md
+- /path/to/reports/researcher-260101-1200-jwt-tradeoffs.md
+
+Work context: /path/to/project
+Reports: /path/to/project/plans/reports/
+Plans: /path/to/project/plans/
+Naming format: {date}-{slug}
+```
+
+### ck-code-review dispatch
+```
+Review changes from the authentication implementation.
+
+Plan file reviewed: /path/to/plan/phase-02-api.md
+Base SHA: abc1234
+Head SHA: def5678
+Changed files: [list]
+
+Work context: /path/to/project
+Reports: /path/to/project/plans/reports/
+```
+
+### ck-web-testing dispatch
+```
+Run the test suite and analyze results.
+
+Recent changes: [list of modified files]
+Test commands: npm test, npm run test:coverage
+
+Work context: /path/to/project
+Reports: /path/to/project/plans/reports/
+```
+
+## Subagent Context Injection (Automatic)
+
+`ck-session-guard` automatically injects a compact context block into every dispatched agent (~200 tokens). This includes plan path, reports path, naming pattern, and core rules.
+
+However, this automatic injection uses the **session's** active plan — not necessarily the plan you want the subagent to work on. Always pass explicit context in the dispatch prompt to override or supplement.
+
+## Naming Pattern Propagation
+
+Subagents must write reports using the naming pattern from their injected `## Naming` section. Never hardcode dates — use the computed pattern:
+
+```
+Report: {reports-path}/ck-code-review-{name-pattern}.md
+```
+
+Where `{name-pattern}` = computed date + optional issue ID, with `{slug}` as the only remaining placeholder.
+
+## Anti-Patterns
+
+- **Omitting work context**: Subagent defaults to its own CWD, which may be wrong
+- **Relative paths**: Always use absolute paths in delegation prompts
+- **Assuming plan propagation**: Active plan in session ≠ plan the subagent should use; pass explicitly
+- **Stale reports path**: If plan was just created, update reports path to plan-specific folder

skills/ck-orchestration/references/documentation-management.md

@@ -0,0 +1,117 @@
+# Documentation Management Protocol
+
+Maintain project documentation in `./docs` after significant changes. Documentation is a living artifact — update it as part of every feature delivery, not as an afterthought.
+
+## When to Update Docs
+
+| Trigger | Documents to Update |
+|---------|---------------------|
+| Feature implementation complete | `codebase-summary.md`, `system-architecture.md`, `development-roadmap.md`, `project-changelog.md` |
+| Bug fix merged | `project-changelog.md` |
+| Architecture decision made | `system-architecture.md`, `codebase-summary.md` |
+| Security update | `project-changelog.md`, `system-architecture.md` |
+| Breaking change | `project-changelog.md`, `code-standards.md` |
+| Phase status change | `development-roadmap.md` |
+| New code patterns established | `code-standards.md` |
+
+## Documents Maintained
+
+```
+./docs/
+├── codebase-summary.md       — Project structure, key files, module overview
+├── system-architecture.md    — Architecture decisions, component interactions, data flow
+├── code-standards.md         — Coding conventions, patterns, anti-patterns
+├── development-roadmap.md    — Phases, milestones, progress tracking
+├── project-changelog.md      — Chronological record of significant changes
+├── design-guidelines.md      — UI/UX design system, tokens, patterns (frontend projects)
+└── deployment-guide.md       — Deployment procedures, environment config
+```
+
+## Update Protocol
+
+### Before Updating
+
+1. Read current state of the document to understand existing content
+2. Identify what changed and how it affects each document
+3. Check cross-references between documents for consistency
+
+### During Updates
+
+- Maintain version consistency (dates, version numbers)
+- Use consistent formatting with the rest of the document
+- Add entries chronologically (newest at top for changelogs)
+- Keep summaries concise — docs are reference material, not tutorials
+
+### After Updating
+
+- Verify links and cross-references are accurate
+- Ensure dates match actual implementation dates
+- Confirm progress percentages reflect reality
+
+## Codebase Summary Freshness
+
+`./docs/codebase-summary.md` has a **2-day staleness threshold**:
+
+- If the file is less than 2 days old: read it as-is for project context
+- If the file is more than 2 days old or doesn't exist: regenerate using `repomix` command, then update the file
+
+```bash
+# Regenerate codebase summary
+repomix
+# Then summarize repomix-output.xml into docs/codebase-summary.md
+```
+
+## Changelog Entry Format
+
+```markdown
+## [YYYY-MM-DD] Feature/Fix Title
+
+### Added
+- New capability or feature
+
+### Changed
+- Modified behavior with before/after context
+
+### Fixed
+- Bug description and impact
+
+### Security
+- Security improvement or vulnerability addressed
+
+### Breaking Changes
+- What broke, migration path
+```
+
+## Roadmap Update Format
+
+```markdown
+## Phase N: Phase Name — [Status: pending/in-progress/complete]
+
+**Progress:** X%
+**Target:** YYYY-MM-DD
+**Actual:** YYYY-MM-DD (if complete)
+
+### Milestones
+- [x] Completed milestone
+- [ ] Pending milestone
+
+### Notes
+Any relevant context about blockers or decisions
+```
+
+## Finalize Step Integration
+
+Documentation updates are part of the mandatory **Finalize** step in `ck-cook`:
+
+1. Update plan/phase status to complete
+2. **Update `./docs` if changes warrant it** ← this step
+3. Ask user if they want to commit via `ck-git`
+
+Never skip the docs update step. Even a one-line changelog entry is better than no record.
+
+## Anti-Patterns
+
+- **Docs as afterthought**: Updating docs days after implementation → inaccurate timestamps and forgotten context
+- **Over-documenting**: Giant walls of text no one reads → keep entries concise and scannable
+- **Stale summaries**: Using a 2-week-old `codebase-summary.md` for project context → regenerate it
+- **Missing breaking changes**: Forgetting to document API breaks → surprises for future developers

skills/ck-orchestration/references/parallel-execution.md

@@ -0,0 +1,97 @@
+# Parallel Execution Patterns
+
+Dispatch multiple agents simultaneously for independent tasks. Maximize throughput when tasks don't share file ownership.
+
+## When to Parallelize
+
+### Research Fan-Out (Most Common)
+
+Dispatch multiple `ck-research` agents simultaneously on different topics, then aggregate into `ck-planning`:
+
+```
+ck-planning receives task
+      │
+      ├──► ck-research: "authentication patterns for FastAPI"
+      ├──► ck-research: "JWT vs session token trade-offs"
+      └──► ck-research: "OAuth 2.1 PKCE implementation"
+                │ (all complete)
+                ▼
+      ck-planning aggregates reports → plan.md
+```
+
+**Max parallel research agents:** 3–5 (respects the 5-query max rule per agent)
+
+### Scout Coverage
+
+Divide a large codebase among multiple `ck-scout` agents by directory:
+
+```
+ck-scout agent 1: src/features/, src/components/
+ck-scout agent 2: src/api/, src/hooks/
+ck-scout agent 3: src/utils/, tests/
+      │ (all complete, timeout 3 min each)
+      ▼
+Aggregate into single scout report
+```
+
+### Independent Feature Components
+
+When implementing a feature with truly independent parts:
+
+```
+ck-cook agent 1: phase-01-database-schema.md  (owns: migrations/)
+ck-cook agent 2: phase-02-api-endpoints.md    (owns: api/)
+ck-cook agent 3: phase-03-ui-components.md    (owns: components/)
+      │ (all complete)
+      ▼
+Integration phase (sequential)
+```
+
+**Prerequisite:** File ownership must be explicitly divided with zero overlap.
+
+### Cross-Platform Development
+
+```
+Developer agent 1: iOS-specific implementation
+Developer agent 2: Android-specific implementation
+      │ (both complete)
+      ▼
+Shared interface verification (sequential)
+```
+
+## Coordination Rules
+
+### Before Parallel Dispatch
+
+1. **Define file ownership**: Which files does each agent exclusively own?
+2. **Identify shared resources**: Are there any files both agents might write?
+3. **Plan merge strategy**: How will outputs be combined?
+4. **Set timeout expectations**: How long should each agent take?
+
+### During Parallel Execution
+
+- Agents work independently — no inter-agent communication
+- Each agent writes to its own report path (different filenames)
+- No agent reads files being written by another agent
+
+### After Parallel Completion
+
+- Wait for ALL agents to complete before proceeding
+- Read all reports before synthesizing
+- Resolve any conflicts manually before the next sequential step
+
+## Parallelization Limits
+
+| Scenario | Max Agents | Reason |
+|----------|------------|--------|
+| Research | 5 | Token budget per agent |
+| Scout | 4 | Codebase coverage vs. overlap |
+| Implementation phases | 3 | File conflict risk |
+| CI/CD verification | Unlimited | Read-only bash commands |
+
+## Anti-Patterns
+
+- **Shared file writes**: Two agents writing the same file causes corruption — assign exclusive ownership
+- **Implicit dependencies**: Agent B needs Agent A's output → must be sequential, not parallel
+- **Too many agents**: Each agent consumes context window; over-parallelizing causes resource contention
+- **No merge plan**: Spawning parallel agents without knowing how to combine results → wasted work

skills/ck-orchestration/references/sequential-chaining.md

@@ -0,0 +1,75 @@
+# Sequential Chaining Patterns
+
+Chain agents when tasks have dependencies or require outputs from previous steps. Each agent completes fully before the next begins.
+
+## Standard Pipelines
+
+### Feature Implementation Pipeline
+
+```
+1. ck-research (parallel, multiple topics)
+        ↓ reports saved to plans/reports/
+2. ck-planning (reads research reports, creates plan.md)
+        ↓ plan path passed explicitly
+3. [/clear context]
+        ↓
+4. ck-cook path/to/plan.md --auto
+        ↓ dispatches internally:
+        ├── ck-scout
+        ├── ck-frontend-design (if UI work)
+        ├── ck-web-testing
+        ├── ck-code-review
+        └── ck-git (on approval)
+```
+
+### Debug + Fix Pipeline
+
+```
+1. ck-debug (investigate root cause)
+        ↓ debug report with findings
+2. ck-fix (implement fix based on findings)
+        ↓ fix applied
+3. ck-web-testing (verify fix, check regressions)
+        ↓ test report
+4. ck-code-review (review changes)
+        ↓ review complete
+5. ck-git (commit and push)
+```
+
+### Research + Design Pipeline
+
+```
+1. ck-research (technology evaluation)
+        ↓ research report
+2. ck-brainstorm (evaluate approaches, choose direction)
+        ↓ brainstorm summary with agreed solution
+3. ck-planning (detailed implementation plan)
+        ↓ plan.md created
+4. ck-cook (execute plan)
+```
+
+## Rules for Sequential Chains
+
+1. **Pass explicit paths** — never assume an agent's output location; read it from the report or plan
+2. **Read before proceeding** — always read the output of step N before dispatching step N+1
+3. **Complete means complete** — an agent is done when its report is written, not when it stops responding
+4. **Context clearing** — after `ck-planning`, clear context (`/clear`) before invoking `ck-cook` to prevent bloated context windows during implementation
+
+## Context Passing Pattern
+
+When dispatching each agent, include the output of all prior steps:
+
+```
+Dispatch ck-fix with:
+- Debug report: plans/reports/debugger-{pattern}.md
+- Plan context: plans/{plan-dir}/
+- Work context: /path/to/project
+- Reports: /path/to/project/plans/reports/
+```
+
+## Chaining Anti-Patterns
+
+- **Skipping steps**: Never skip `ck-web-testing` before `ck-code-review` — tests must pass first
+- **Parallel when dependent**: If step B needs step A's output, they cannot run in parallel
+- **Assuming completion**: Never proceed to next step based on "seems done" — verify report file exists
+- **Ignoring failures**: If any step reports failures, fix before continuing the chain