cfsa-antigravity 1.0.0

package/template/.agent/skills/bootstrap-agents/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: bootstrap-agents
+description: "Utility — fill {{PLACEHOLDER}} values and provision skills from the library. Called by pipeline commands when tech stack info changes."
+version: 2.0.0
+---
+
+# Bootstrap Agents
+
+**This is a utility command, not an entry point.** It gets called by other pipeline commands (like `/create-prd`, `/iterate-plan`, `/write-be-spec`, `/write-fe-spec`, `/add-feature`, `/implement-slice`) whenever they make tech stack decisions or introduce new dependencies.
+
+Bootstrap does two things:
+1. **Fill `{{PLACEHOLDER}}` values** in kit instruction templates
+2. **Provision skills** from `skill-library/` based on stack and surface triggers
+
+**Input**: Template values (package manager, framework, database, etc.) + optional stack/surface triggers
+**Output**: Filled templates + newly installed skills in `.claude/skills/`
+
+---
+
+## 1. Receive template values
+
+The calling command provides these values (all optional — fill only what's provided, leave others as `{{PLACEHOLDER}}`):
+
+### Command & Tool Values
+
+| Key | Example |
+|-----|---------|
+| `PACKAGE_MANAGER` | pnpm |
+| `DEV_COMMAND` | pnpm dev |
+| `TEST_COMMAND` | pnpm test |
+| `TEST_WATCH_COMMAND` | pnpm test:watch |
+| `TEST_COVERAGE_COMMAND` | pnpm test:coverage |
+| `LINT_COMMAND` | pnpm lint |
+| `LINT_FIX_COMMAND` | pnpm lint:fix |
+| `FORMAT_COMMAND` | pnpm format |
+| `TYPE_CHECK_COMMAND` | pnpm type-check |
+| `BUILD_COMMAND` | pnpm build |
+| `PREVIEW_COMMAND` | pnpm preview |
+| `VALIDATION_COMMAND` | pnpm test && pnpm lint && pnpm type-check && pnpm build |
+
+### Project Identity
+
+| Key | Example |
+|-----|---------|
+| `PROJECT_NAME` | My Project |
+| `DESCRIPTION` | One-line description |
+| `TECH_STACK_SUMMARY` | Astro + React + SurrealDB + Firebase Auth |
+
+### Architecture & Structure
+
+| Key | Example |
+|-----|---------|
+| `FRAMEWORK_PATTERNS` | Framework-specific patterns block |
+| `PROJECT_STRUCTURE` | Directory layout block |
+| `ARCHITECTURE_TABLE` | Concern/Location/Runtime table rows |
+| `ARCHITECTURE_DOC` | docs/plans/2026-02-10-architecture-design.md |
+| `CONTRACTS_DIR` | src/contracts/ |
+| `BUILD_OUTPUT_DIR` | dist/ |
+
+### Stack Values (trigger skill provisioning)
+
+| Key | Example |
+|-----|---------|
+| `DATABASE` | SurrealDB (self-hosted) |
+| `FRONTEND_FRAMEWORK` | Astro + React Islands |
+| `BACKEND_FRAMEWORK` | Hono |
+| `API_LAYER` | tRPC |
+| `BACKEND_RUNTIME` | Cloudflare Workers |
+| `ORM` | Drizzle |
+| `CSS_FRAMEWORK` | Tailwind CSS v4 |
+| `UI_LIBRARY` | shadcn/ui |
+| `AUTH_PROVIDER` | Firebase Auth |
+| `PAYMENTS` | Stripe |
+| `AI_SDK` | Vercel AI SDK |
+| `STATE_MANAGEMENT` | TanStack Query |
+| `E2E_TESTING` | Playwright |
+| `UNIT_TESTING` | Vitest |
+| `HOSTING` | Cloudflare Pages + Workers |
+| `CDN_ASSETS` | Cloudflare R2 |
+| `MONITORING` | Sentry |
+| `ANALYTICS` | Google Analytics |
+| `EMAIL` | Resend |
+| `QUEUE` | Inngest |
+| `REALTIME` | Socket.io |
+| `SEARCH` | Meilisearch |
+| `CMS` | Payload CMS |
+| `STORAGE` | AWS S3 |
+| `CI_CD` | GitHub Actions |
+| `MOBILE_FRAMEWORK` | Expo |
+| `LANGUAGE` | TypeScript |
+| `3D_FRAMEWORK` | Three.js / R3F |
+| `DESKTOP_FRAMEWORK` | Tauri |
+| `GAME_ENGINE` | Godot |
+| `SECURITY` | OWASP |
+| `TEST_RUNNER` | Vitest |
+| `LINTER` | ESLint |
+| `TYPE_CHECKER` | TypeScript (tsc) |
+
+### Infrastructure Values
+
+| Key | Example |
+|-----|---------|
+| `SSH_HOST` | my-vps |
+| `DB_PORT` | 19000 |
+| `CREDENTIAL_TOOL` | agent-auth ssh-add |
+| `SECRET_MANAGEMENT` | wrangler secret |
+| `DEPLOY_COMMAND` | wrangler deploy |
+
+### Surface Types
+
+| Key | Example |
+|-----|---------|
+| `SURFACES` | web, api |
+
+If any values are missing, leave those `{{PLACEHOLDER}}`s in place — they'll be filled on a future invocation.
+
+---
+
+## 2. Fill project skill templates
+
+### `.claude/skills/project-commands/SKILL.md`
+Replace: `{{PACKAGE_MANAGER}}`, `{{DEV_COMMAND}}`, `{{TEST_COMMAND}}`, `{{TEST_WATCH_COMMAND}}`, `{{TEST_COVERAGE_COMMAND}}`, `{{LINT_COMMAND}}`, `{{LINT_FIX_COMMAND}}`, `{{FORMAT_COMMAND}}`, `{{TYPE_CHECK_COMMAND}}`, `{{BUILD_COMMAND}}`, `{{PREVIEW_COMMAND}}`, `{{VALIDATION_COMMAND}}`
+
+### `.claude/skills/project-workflow/SKILL.md`
+Replace: `{{VALIDATION_COMMAND}}`
+
+### `.claude/skills/project-patterns/SKILL.md`
+Replace: `{{FRAMEWORK_PATTERNS}}` if provided
+
+### `.claude/skills/project-structure/SKILL.md`
+Replace: `{{PROJECT_STRUCTURE}}`, `{{ARCHITECTURE_TABLE}}` if provided
+
+### `.claude/skills/project-tech-stack/SKILL.md`
+Replace: `{{TECH_STACK_SUMMARY}}`, `{{FRONTEND_FRAMEWORK}}`, `{{BACKEND_RUNTIME}}`, `{{DATABASE}}`, `{{AUTH_PROVIDER}}`, `{{HOSTING}}`, `{{CDN_ASSETS}}`, `{{CICD}}`, `{{MONITORING}}`, `{{PACKAGE_MANAGER}}`, `{{TEST_RUNNER}}`, `{{LINTER}}`, `{{TYPE_CHECKER}}`, `{{INSTALLED_SKILLS}}`
+
+---
+
+## 3. Fill default operational skill templates
+
+Scan all `.claude/skills/*/SKILL.md` files for `{{PLACEHOLDER}}` values and fill any that match the provided template values:
+
+- `{{VALIDATION_COMMAND}}` — in `fix-bug`, `main-workflow`, `deploy`, `refactor`
+- `{{PACKAGE_MANAGER}}` — in `refactor`, `security-audit`
+- `{{TEST_COVERAGE_COMMAND}}` — in `refactor`
+- `{{BUILD_COMMAND}}` — in `deploy`
+- `{{DEPLOY_COMMAND}}` — in `deploy`
+- `{{BUILD_OUTPUT_DIR}}` — in `deploy`
+- `{{SSH_HOST}}` — in `setup-session`
+- `{{DB_PORT}}` — in `setup-session`
+- `{{CREDENTIAL_TOOL}}` — in `setup-session`
+
+---
+
+## 4. Fill rule templates
+
+### `.claude/rules/contract-first.md`
+Replace: `{{VALIDATION_COMMAND}}`, `{{TEST_RUNNER}}`
+
+---
+
+## 5. Fill CLAUDE.md
+
+Replace in `CLAUDE.md` at project root:
+- `{{PROJECT_NAME}}`
+- `{{DESCRIPTION}}`
+- `{{TECH_STACK_SUMMARY}}`
+- `{{VALIDATION_COMMAND}}`
+
+---
+
+## 6. Read skill library manifest
+
+Read `skill-library/MANIFEST.md` to load the trigger tables.
+
+If `skill-library/MANIFEST.md` does not exist (e.g., user deleted it or is using a minimal kit), skip steps 7-8 and go to step 9.
+
+---
+
+## 7. Provision skills from library
+
+For each stack key provided in the template values, check the **Stack Triggers** table in the manifest:
+
+1. Match the provided value against the manifest's `Value Pattern` (case-insensitive)
+2. If a match is found AND the skill is NOT already in `.claude/skills/[installed-as]/`:
+   - Copy the entire directory from `skill-library/[library-path]/` → `.claude/skills/[installed-as]/`
+   - Fill any `{{PLACEHOLDER}}`s in the newly-copied `SKILL.md` with current template values
+3. If the skill already exists in `.claude/skills/`, skip it (idempotent)
+
+For each surface type provided in `SURFACES`, check the **Surface Triggers** table:
+
+1. Match the surface type against the manifest's `Surface Type` column
+2. Copy matching skills that don't already exist, same as above
+
+### Matching rules
+
+| Manifest Pattern | Matches |
+|-----------------|---------|
+| `*surrealdb*` | "SurrealDB", "surrealdb (self-hosted)", "SurrealDB Cloud" |
+| `*cloudflare*` | "Cloudflare Workers", "Cloudflare Pages + Workers" |
+| `*tailwind*` | "Tailwind CSS v4", "Tailwind CSS" |
+| `*vercel*` OR `*ai-sdk*` | "Vercel AI SDK", "AI SDK" |
+| `*three*` OR `*r3f*` | "Three.js", "React Three Fiber", "R3F" |
+
+Pattern matching is glob-style with `*` as wildcard, case-insensitive.
+
+---
+
+## 8. Update installed skills list
+
+After provisioning, build a markdown list of all installed skills (both defaults and library-provisioned) and update `{{INSTALLED_SKILLS}}` in `project-tech-stack`:
+
+```markdown
+### Default Skills
+- fix-bug — TDD bug fix workflow
+- refactor — Safe refactoring with test verification
+- add-feature — Add feature to existing architecture
+- deploy — Full deployment pipeline
+- pr-review — Structured PR review
+- security-audit — Security review across all layers
+- main-workflow — General development workflow
+- iterate-plan — Tech stack gap analysis
+- setup-session — Session initialization
+- using-git-worktrees — Isolated workspace management
+- github-workflow-automation — GitHub CI/CD patterns
+- audit-context-building — Deep code analysis
+- context7-auto-research — Auto documentation lookup
+- self-improving-agent — Learning from experiences
+
+### Stack Skills
+- [skill-name] — [description] (installed for [STACK_KEY]=[value])
+- ...
+
+### Surface Skills
+- [skill-name] — [description] (installed for [surface] surface)
+- ...
+```
+
+---
+
+## 9. Report results
+
+Present the results to the calling command (not directly to the user — the calling command handles user communication):
+
+- Which `{{PLACEHOLDER}}`s were filled (and their values)
+- Which `{{PLACEHOLDER}}`s remain unfilled
+- Which skills were provisioned from the library (if any)
+- Which skills were already installed and skipped
+- Any errors (missing files, missing library paths)
+
+---
+
+## Idempotency
+
+Bootstrap is safe to call multiple times:
+
+- **Already-filled placeholders**: If a `{{PLACEHOLDER}}` has already been replaced with a value, it is NOT re-filled unless the calling command explicitly provides a new value for that key
+- **Already-installed skills**: Skills that already exist in `.claude/skills/` are not re-copied from the library
+- **New values**: New stack/surface values trigger new skill installations without affecting existing ones
+- **Partial invocation**: Bootstrap can be called with just one or two new values — it only fills what's provided

package/template/.agent/skills/brainstorming/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+risk: unknown
+source: merged (local + community)
+date_added: "2026-02-27"
+---
+
+# Brainstorming Ideas Into Designs
+
+## Purpose
+
+Turn raw ideas into **clear, validated designs and specifications**
+through structured dialogue **before any implementation begins**.
+
+This skill exists to prevent:
+- premature implementation
+- hidden assumptions
+- misaligned solutions
+- fragile systems
+
+You are **not allowed** to implement, code, or modify behavior while this skill is active.
+
+---
+
+## Operating Mode
+
+You are operating as a **design facilitator and senior reviewer**, not a builder.
+
+- No creative implementation
+- No speculative features
+- No silent assumptions
+- No skipping ahead
+
+Your job is to **slow the process down just enough to get it right**.
+
+---
+
+## The Process
+
+### 1️⃣ Understand the Current Context (Mandatory First Step)
+
+Before asking any questions:
+
+- Review the current project state (if available):
+  - files
+  - documentation
+  - plans
+  - prior decisions
+  - recent commits
+- Identify what already exists vs. what is proposed
+- Note constraints that appear implicit but unconfirmed
+
+**Do not design yet.**
+
+---
+
+### 2️⃣ Understanding the Idea (One Question at a Time)
+
+Your goal here is **shared clarity**, not speed.
+
+**Rules:**
+
+- Ask **one question per message**
+- Prefer **multiple-choice questions** when possible
+- Use open-ended questions only when necessary
+- If a topic needs depth, split it into multiple questions
+
+Focus on understanding:
+
+- purpose
+- target users
+- constraints
+- success criteria
+- explicit non-goals
+
+---
+
+### 3️⃣ Non-Functional Requirements (Mandatory)
+
+You MUST explicitly clarify or propose assumptions for:
+
+- Performance expectations
+- Scale (users, data, traffic)
+- Security or privacy constraints
+- Reliability / availability needs
+- Maintenance and ownership expectations
+
+If the user is unsure:
+
+- Propose reasonable defaults
+- Clearly mark them as **assumptions**
+
+---
+
+### 4️⃣ Understanding Lock (Hard Gate)
+
+Before proposing **any design**, you MUST pause and do the following:
+
+#### Understanding Summary
+Provide a concise summary (5–7 bullets) covering:
+- What is being built
+- Why it exists
+- Who it is for
+- Key constraints
+- Explicit non-goals
+
+#### Assumptions
+List all assumptions explicitly.
+
+#### Open Questions
+List unresolved questions, if any.
+
+Then ask:
+
+> "Does this accurately reflect your intent?
+> Please confirm or correct anything before we move to design."
+
+**Do NOT proceed until explicit confirmation is given.**
+
+---
+
+### 5️⃣ Explore Design Approaches
+
+Once understanding is confirmed:
+
+- Propose **2–3 viable approaches**
+- Lead with your **recommended option** and explain why
+- Explain trade-offs clearly:
+  - complexity
+  - extensibility
+  - risk
+  - maintenance
+- Avoid premature optimization (**YAGNI ruthlessly**)
+
+This is still **not** final design.
+
+---
+
+### 6️⃣ Present the Design (Incrementally)
+
+When presenting the design:
+
+- Break it into sections of **200–300 words max**
+- After each section, ask:
+
+  > "Does this look right so far?"
+
+Cover, as relevant:
+
+- Architecture
+- Components
+- Data flow
+- Error handling
+- Edge cases
+- Testing strategy
+
+Be ready to go back and clarify if something doesn't make sense.
+
+---
+
+### 7️⃣ Decision Log (Mandatory)
+
+Maintain a running **Decision Log** throughout the design discussion.
+
+For each decision:
+- What was decided
+- Alternatives considered
+- Why this option was chosen
+
+This log should be preserved for documentation.
+
+---
+
+## After the Design
+
+### 📄 Documentation
+
+Once the design is validated:
+
+- Write the final design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Include:
+  - Understanding summary
+  - Assumptions
+  - Decision log
+  - Final design
+- Commit the design document to git
+
+---
+
+### 🛠️ Implementation Handoff (Optional)
+
+Only after documentation is complete, ask:
+
+> "Ready to set up for implementation?"
+
+If yes:
+- Check `.agent/skills/` for relevant workflow skills (e.g., `create-prd`, `plan-phase`)
+- Create an explicit implementation plan
+- Proceed incrementally
+
+---
+
+## Exit Criteria (Hard Stop Conditions)
+
+You may exit brainstorming mode **only when all of the following are true**:
+
+- Understanding Lock has been confirmed
+- At least one design approach is explicitly accepted
+- Major assumptions are documented
+- Key risks are acknowledged
+- Decision Log is complete
+
+If any criterion is unmet:
+- Continue refinement
+- **Do NOT proceed to implementation**
+
+---
+
+## Key Principles (Non-Negotiable)
+
+- **One question at a time** — Don't overwhelm with multiple questions
+- **Multiple choice preferred** — Easier to answer than open-ended when possible
+- **Assumptions must be explicit** — Never silently assume
+- **YAGNI ruthlessly** — Remove unnecessary features from all designs
+- **Explore alternatives** — Always propose 2–3 approaches before settling
+- **Incremental validation** — Present design in sections, validate each
+- **Prefer clarity over cleverness** — Simple > smart
+- **Be flexible** — Go back and clarify when something doesn't make sense
+
+---
+
+If the design is high-impact, high-risk, or requires elevated confidence, you MUST hand off the finalized design and Decision Log to the `multi-agent-brainstorming` skill before implementation.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/template/.agent/skills/brand-guidelines/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: brand-guidelines
+description: "Apply the confirmed design direction to all visual surfaces. If `{{DESIGN_DIRECTION}}` still appears as a literal placeholder, the design direction has not been confirmed — run `/create-prd` first."
+---
+
+# {{PROJECT_NAME}} Brand Guidelines
+
+> **Status**: {{#if DESIGN_DIRECTION}}Active{{else}}⚠️ UNFILLED — Run /create-prd to confirm design direction before using this skill{{/if}}
+
+## Design Direction
+
+- **Confirmed direction**: {{DESIGN_DIRECTION}}
+- **Rationale**: {{DESIGN_DIRECTION_RATIONALE}}
+- **Primary audience**: {{DESIGN_AUDIENCE}}
+
+## Color Palette
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Primary | {{PRIMARY_COLOR}} | Main brand color — buttons, links, key UI elements |
+| Secondary | {{SECONDARY_COLOR}} | Supporting color — secondary actions, accents |
+| Accent | {{ACCENT_COLOR}} | Highlight color — notifications, badges, emphasis |
+| Background | {{BACKGROUND_COLOR}} | Page/app background |
+| Text | {{TEXT_COLOR}} | Primary text color |
+
+## Typography
+
+| Role | Font | Usage |
+|------|------|-------|
+| Heading | {{HEADING_FONT}} | Page titles, section headers, display text |
+| Body | {{BODY_FONT}} | Paragraphs, descriptions, UI labels |
+| Mono | {{MONO_FONT}} | Code blocks, terminal output, technical values |
+
+## Motion Philosophy
+
+{{MOTION_PHILOSOPHY}}
+
+## Existing Brand Assets
+
+{{EXISTING_BRAND_ASSETS}}
+
+## What to Avoid
+
+{{DESIGN_AVOID}}

package/template/.agent/skills/clean-code/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: clean-code
+description: "Applies principles from Robert C. Martin's 'Clean Code'. Use this skill when writing, reviewing, or refactoring code to ensure high quality, readability, and maintainability. Covers naming, functions, comments, error handling, and class design."
+user-invocable: true
+risk: safe
+source: "ClawForge (https://github.com/jackjin1997/ClawForge)"
+---
+
+# Clean Code Skill
+
+This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean."
+
+## 🧠 Core Philosophy
+> "Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch
+
+## When to Use
+Use this skill when:
+- **Writing new code**: To ensure high quality from the start.
+- **Reviewing Pull Requests**: To provide constructive, principle-based feedback.
+- **Refactoring legacy code**: To identify and remove code smells.
+- **Improving team standards**: To align on industry-standard best practices.
+
+## 1. Meaningful Names
+- **Use Intention-Revealing Names**: `elapsedTimeInDays` instead of `d`.
+- **Avoid Disinformation**: Don't use `accountList` if it's actually a `Map`.
+- **Make Meaningful Distinctions**: Avoid `ProductData` vs `ProductInfo`.
+- **Use Pronounceable/Searchable Names**: Avoid `genymdhms`.
+- **Class Names**: Use nouns (`Customer`, `WikiPage`). Avoid `Manager`, `Data`.
+- **Method Names**: Use verbs (`postPayment`, `deletePage`).
+
+## 2. Functions
+- **Small!**: Functions should be shorter than you think.
+- **Do One Thing**: A function should do only one thing, and do it well.
+- **One Level of Abstraction**: Don't mix high-level business logic with low-level details (like regex).
+- **Descriptive Names**: `isPasswordValid` is better than `check`.
+- **Arguments**: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification.
+- **No Side Effects**: Functions shouldn't secretly change global state.
+
+## 3. Comments
+- **Don't Comment Bad Code—Rewrite It**: Most comments are a sign of failure to express ourselves in code.
+- **Explain Yourself in Code**: 
+  ```python
+  # Check if employee is eligible for full benefits
+  if employee.flags & HOURLY and employee.age > 65:
+  ```
+  vs
+  ```python
+  if employee.isEligibleForFullBenefits():
+  ```
+- **Good Comments**: Legal, Informative (regex intent), Clarification (external libraries), TODOs.
+- **Bad Comments**: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers.
+
+## 4. Formatting
+- **The Newspaper Metaphor**: High-level concepts at the top, details at the bottom.
+- **Vertical Density**: Related lines should be close to each other.
+- **Distance**: Variables should be declared near their usage.
+- **Indentation**: Essential for structural readability.
+
+## 5. Objects and Data Structures
+- **Data Abstraction**: Hide the implementation behind interfaces.
+- **The Law of Demeter**: A module should not know about the innards of the objects it manipulates. Avoid `a.getB().getC().doSomething()`.
+- **Data Transfer Objects (DTO)**: Classes with public variables and no functions.
+
+## 6. Error Handling
+- **Use Exceptions instead of Return Codes**: Keeps logic clean.
+- **Write Try-Catch-Finally First**: Defines the scope of the operation.
+- **Don't Return Null**: It forces the caller to check for null every time.
+- **Don't Pass Null**: Leads to `NullPointerException`.
+
+## 7. Unit Tests
+- **The Three Laws of TDD**:
+  1. Don't write production code until you have a failing unit test.
+  2. Don't write more of a unit test than is sufficient to fail.
+  3. Don't write more production code than is sufficient to pass the failing test.
+- **F.I.R.S.T. Principles**: Fast, Independent, Repeatable, Self-Validating, Timely.
+
+## 8. Classes
+- **Small!**: Classes should have a single responsibility (SRP).
+- **The Stepdown Rule**: We want the code to read like a top-down narrative.
+
+## 9. Smells and Heuristics
+- **Rigidity**: Hard to change.
+- **Fragility**: Breaks in many places.
+- **Immobility**: Hard to reuse.
+- **Viscosity**: Hard to do the right thing.
+- **Needless Complexity/Repetition**.
+
+## 🛠️ Implementation Checklist
+- [ ] Is this function smaller than 20 lines?
+- [ ] Does this function do exactly one thing?
+- [ ] Are all names searchable and intention-revealing?
+- [ ] Have I avoided comments by making the code clearer?
+- [ ] Am I passing too many arguments?
+- [ ] Is there a failing test for this change?