@xaviele/ag-kit 1.0.0

package/template/.agent/skills/doc.md

@@ -0,0 +1,177 @@
+# Antigravity Skills
+
+> **Guide to creating and using Skills in the Antigravity Kit**
+
+---
+
+## 📋 Overview
+
+While Antigravity's base models (like Gemini) are powerful generalists, they don't know your specific project context or your team's standards. Loading every rule or tool into the agent's context window leads to "tool bloat," higher costs, latency, and confusion.
+
+**Antigravity Skills** solve this through **Progressive Disclosure**. A Skill is a package of specialized knowledge that remains dormant until needed. This information is only loaded into the agent's context when your specific request matches the skill's description.
+
+---
+
+## 📁 Structure and Scope
+
+Skills are folder-based packages. You can define these scopes based on your needs:
+
+| Scope         | Path                              | Description                          |
+| ------------- | --------------------------------- | ------------------------------------ |
+| **Workspace** | `<workspace-root>/.agent/skills/` | Available only in a specific project |
+
+### Skill Directory Structure
+
+```
+my-skill/
+├── SKILL.md      # (Required) Metadata & instructions
+├── scripts/      # (Optional) Python or Bash scripts
+├── references/   # (Optional) Text, documentation, templates
+└── assets/       # (Optional) Images or logos
+```
+
+---
+
+## 🔍 Example 1: Code Review Skill
+
+This is an instruction-only skill; you only need to create the `SKILL.md` file.
+
+### Step 1: Create the directory
+
+```bash
+mkdir -p .agent/skills/code-review
+```
+
+### Step 2: Create SKILL.md
+
+```markdown
+---
+name: code-review
+description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing PRs or checking code quality.
+---
+
+# Code Review Skill
+
+When reviewing code, follow these steps:
+
+## Review checklist
+
+1. **Correctness**: Does the code do what it's supposed to?
+2. **Edge cases**: Are error conditions handled?
+3. **Style**: Does it follow project conventions?
+4. **Performance**: Are there obvious inefficiencies?
+
+## How to provide feedback
+
+- Be specific about what needs to change
+- Explain why, not just what
+- Suggest alternatives when possible
+```
+
+> **Note**: The `SKILL.md` file contains metadata (name, description) at the top, followed by the instructions. The agent will only read the metadata and load the full instructions only when needed.
+
+### Try it out
+
+Create a file `demo_bad_code.py`:
+
+```python
+import time
+
+def get_user_data(users, id):
+    # Find user by ID
+    for u in users:
+        if u['id'] == id:
+            return u
+    return None
+
+def process_payments(items):
+    total = 0
+    for i in items:
+        # Calculate tax
+        tax = i['price'] * 0.1
+        total = total + i['price'] + tax
+        time.sleep(0.1)  # Simulate slow network call
+    return total
+
+def run_batch():
+    users = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
+    items = [{'price': 10}, {'price': 20}, {'price': 100}]
+
+    u = get_user_data(users, 3)
+    print("User found: " + u['name'])  # Will crash if None
+
+    print("Total: " + str(process_payments(items)))
+
+if __name__ == "__main__":
+    run_batch()
+```
+
+**Prompt**: `review the @demo_bad_code.py file`
+
+The Agent will automatically identify the `code-review` skill, load the information, and follow the instructions.
+
+---
+
+## 📄 Example 2: License Header Skill
+
+This skill uses a reference file in the `resources/` (or `references/`) directory.
+
+### Step 1: Create the directory
+
+```bash
+mkdir -p .agent/skills/license-header-adder/resources
+```
+
+### Step 2: Create the template file
+
+**`.agent/skills/license-header-adder/resources/HEADER.txt`**:
+
+```
+/*
+ * Copyright (c) 2026 YOUR_COMPANY_NAME LLC.
+ * All rights reserved.
+ * This code is proprietary and confidential.
+ */
+```
+
+### Step 3: Create SKILL.md
+
+**`.agent/skills/license-header-adder/SKILL.md`**:
+
+```markdown
+---
+name: license-header-adder
+description: Adds the standard corporate license header to new source files.
+---
+
+# License Header Adder
+
+This skill ensures that all new source files have the correct copyright header.
+
+## Instructions
+
+1. **Read the Template**: Read the content of `resources/HEADER.txt`.
+2. **Apply to File**: When creating a new file, prepend this exact content.
+3. **Adapt Syntax**:
+   - For C-style languages (Java, TS), keep the `/* */` block.
+   - For Python/Shell, convert to `#` comments.
+```
+
+### Try it out
+
+**Prompt**: `Create a new Python script named data_processor.py that prints 'Hello World'.`
+
+The Agent will read the template, convert the comments to Python style, and automatically add it to the top of the file.
+
+---
+
+## 🎯 Conclusion
+
+By creating Skills, you transform a general AI model into an expert for your project:
+
+- ✅ Systematize best practices
+- ✅ Adhere to code review rules
+- ✅ Automatically add license headers
+- ✅ The Agent automatically knows how to work with your team
+
+Instead of constantly reminding the AI to "remember to add the license" or "fix the commit format," now the Agent will do it automatically!

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

@@ -0,0 +1,250 @@
+---
+name: document
+description: "Audit your project's documentation health and identify gaps. Scans for README, changelog, API docs, ADRs, runbooks, onboarding guides, and diagrams. Scores coverage against project maturity tier and recommends specific sub-skills to fill missing docs. Use when you need a documentation audit, want to check doc coverage, find missing documentation, or assess documentation quality."
+version: 2.0.0
+category: docs
+---
+
+You are in AUTONOMOUS MODE. Do NOT ask questions. Analyze the project's
+documentation landscape and produce a comprehensive health report.
+
+INPUT:
+$ARGUMENTS
+
+If no arguments provided, perform a full documentation audit of the current project.
+If a specific doc type is mentioned (e.g., "api", "adr", "runbook"), focus the audit
+on that area and route to the appropriate sub-skill.
+
+============================================================
+PHASE 1: AUTO-DETECT PROJECT CONTEXT
+============================================================
+
+Detect the project's tech stack and maturity level:
+
+Step 1.1 -- Tech Stack Detection
+
+Scan for config files to determine the stack:
+- package.json, tsconfig.json (Node.js / TypeScript)
+- pubspec.yaml (Flutter / Dart)
+- Cargo.toml (Rust)
+- go.mod (Go)
+- pyproject.toml, requirements.txt, setup.py (Python)
+- Gemfile (Ruby)
+- pom.xml, build.gradle (Java / Kotlin)
+- docker-compose.yml, Dockerfile (containerized)
+- .github/workflows/ (CI/CD)
+
+Step 1.2 -- Maturity Assessment
+
+Classify the project into a maturity tier:
+
+| Tier | Criteria |
+|------|----------|
+| Greenfield | < 20 commits, no tests, no CI |
+| Active Development | 20-200 commits, some tests, basic CI |
+| Mature | 200+ commits, test suite, CI/CD, deployments |
+| Production | All of Mature + monitoring, runbooks, on-call |
+
+Record the tier -- it determines which docs are expected.
+
+============================================================
+PHASE 2: DOCUMENTATION INVENTORY
+============================================================
+
+Scan the project for existing documentation artifacts:
+
+Step 2.1 -- Core Docs
+
+Check for each of these files/directories and record status (present/missing/stale):
+
+| Document | Paths to Check |
+|----------|---------------|
+| README | README.md, README, readme.md |
+| Changelog | CHANGELOG.md, CHANGES.md, HISTORY.md |
+| Contributing | CONTRIBUTING.md, docs/contributing.md |
+| License | LICENSE, LICENSE.md, COPYING |
+| Code of Conduct | CODE_OF_CONDUCT.md |
+
+Step 2.2 -- API Documentation
+
+Check for:
+- OpenAPI/Swagger specs: openapi.yaml, openapi.json, swagger.yaml, swagger.json
+- docs/api/, api-docs/ directories
+- Inline API doc comments (JSDoc @route, Python docstrings with endpoint info)
+- GraphQL schema files: schema.graphql, *.graphqls
+- Postman collections: *.postman_collection.json
+
+Step 2.3 -- Architecture Docs
+
+Check for:
+- docs/adr/, adr/, decisions/ directories
+- Architecture diagrams: docs/diagrams/, docs/architecture/
+- Mermaid files: *.mmd, *.mermaid
+- Draw.io files: *.drawio
+- C4 model files
+
+Step 2.4 -- Operations Docs
+
+Check for:
+- Runbooks: docs/runbook/, runbook/, playbooks/
+- Deployment docs: docs/deployment/, DEPLOYMENT.md
+- Incident response: docs/incidents/, INCIDENT.md
+- Monitoring: docs/monitoring/, alerts/
+
+Step 2.5 -- Onboarding Docs
+
+Check for:
+- CONTRIBUTING.md, docs/onboarding.md, docs/getting-started.md
+- .env.example, .env.template (environment setup docs)
+- Makefile, scripts/ (developer workflow tooling)
+- docs/development.md, DEVELOPMENT.md
+
+============================================================
+PHASE 3: GAP ANALYSIS
+============================================================
+
+Score each documentation area based on project maturity tier:
+
+SCORING MATRIX:
+
+| Document Type | Greenfield | Active Dev | Mature | Production |
+|--------------|-----------|-----------|--------|-----------|
+| README | Required | Required | Required | Required |
+| Changelog | Optional | Recommended | Required | Required |
+| API Docs | Optional | Recommended | Required | Required |
+| ADRs | Optional | Optional | Recommended | Required |
+| Runbook | N/A | Optional | Recommended | Required |
+| Onboarding | Optional | Recommended | Required | Required |
+| Diagrams | Optional | Optional | Recommended | Required |
+| License | Required | Required | Required | Required |
+
+For each doc type, assign a status:
+- PASS: Document exists and appears current (modified within last 30 days or content matches code)
+- STALE: Document exists but may be outdated (last modified 90+ days ago)
+- MISSING: Document does not exist but is Required/Recommended for this tier
+- N/A: Not expected for this maturity tier
+
+Calculate coverage score: (PASS count / Required+Recommended count) * 100
+
+============================================================
+PHASE 4: ROUTE TO SUB-SKILLS
+============================================================
+
+Based on identified gaps, recommend specific sub-skills to run:
+
+| Gap | Sub-Skill | Command |
+|-----|-----------|---------|
+| Missing/stale README | /readme | Generate comprehensive README |
+| Missing API docs | /api-docs | Auto-generate OpenAPI spec |
+| Missing changelog | /changelog | Generate from git history |
+| Missing ADRs | /adr | Create ADR directory + retrospective ADRs |
+| Missing runbook | /runbook | Generate operations runbook |
+| Missing onboarding | /onboarding | Generate developer onboarding guide |
+| Missing diagrams | /diagram | Generate architecture diagrams |
+
+If $ARGUMENTS specifies a particular doc type, execute that sub-skill's work
+inline rather than just recommending it.
+
+============================================================
+PHASE 5: DOCUMENTATION HEALTH REPORT
+============================================================
+
+OUTPUT:
+
+## Documentation Health Report
+
+### Project Context
+- **Project:** [name from config]
+- **Tech Stack:** [detected stack]
+- **Maturity Tier:** [tier]
+- **Total Commits:** [count]
+
+### Coverage Score: [X]%
+
+### Documentation Inventory
+
+| Document | Status | Path | Last Updated | Notes |
+|----------|--------|------|-------------|-------|
+| README | PASS/STALE/MISSING | path or -- | date or -- | details |
+| Changelog | ... | ... | ... | ... |
+| API Docs | ... | ... | ... | ... |
+| ADRs | ... | ... | ... | ... |
+| Runbook | ... | ... | ... | ... |
+| Onboarding | ... | ... | ... | ... |
+| Diagrams | ... | ... | ... | ... |
+| License | ... | ... | ... | ... |
+
+### Priority Actions
+
+Ordered list of documentation gaps to address, highest priority first:
+
+1. **[MISSING/STALE] [Doc Type]** -- [Why it matters for this project]
+   Run: `/[sub-skill]`
+2. ...
+
+### Documentation Quality Notes
+
+- [Any observations about existing doc quality, consistency, accuracy]
+- [Suggestions for improving existing docs that are present but weak]
+
+
+============================================================
+SELF-HEALING VALIDATION (max 2 iterations)
+============================================================
+
+After producing documentation, validate completeness:
+
+1. Verify all required sections are present and non-empty.
+2. Verify internal cross-references and links resolve correctly.
+3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc.").
+4. Verify code examples are syntactically valid.
+
+IF VALIDATION FAILS:
+- Identify which sections are incomplete or contain placeholders
+- Re-generate only the deficient sections
+- Repeat up to 2 iterations
+
+
+============================================================
+SELF-EVOLUTION TELEMETRY
+============================================================
+
+After producing output, record execution metadata for the /evolve pipeline.
+
+Check if a project memory directory exists:
+- Look for the project path in `~/.claude/projects/`
+- If found, append to `skill-telemetry.md` in that memory directory
+
+Entry format:
+```
+### /document — {{YYYY-MM-DD}}
+- Outcome: {{SUCCESS | PARTIAL | FAILED}}
+- Self-healed: {{yes — what was healed | no}}
+- Iterations used: {{N}} / {{N max}}
+- Bottleneck: {{phase that struggled or "none"}}
+- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
+```
+
+Only log if the memory directory exists. Skip silently if not found.
+Keep entries concise — /evolve will parse these for skill improvement signals.
+
+============================================================
+DO NOT
+============================================================
+
+- Do NOT create or modify any documentation files in this orchestrator skill.
+  Only audit and report. Sub-skills handle the actual generation.
+- Do NOT guess about project features. Only report what you can verify.
+- Do NOT count auto-generated files (lock files, build output) as documentation.
+- Do NOT recommend docs that are genuinely unnecessary for the project type
+  (e.g., runbooks for a CLI tool with no deployment).
+
+NEXT STEPS:
+
+After reviewing the health report:
+- "Run `/api-docs` to generate OpenAPI documentation for your API."
+- "Run `/changelog` to generate a changelog from git history."
+- "Run `/adr retrospective` to create ADRs from existing codebase decisions."
+- "Run `/runbook` to generate an operations runbook."
+- "Run `/onboarding` to generate a developer onboarding guide."
+- "Run `/diagram` to generate architecture diagrams."

package/template/.agent/skills/documentation-templates/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: documentation-templates
+description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
+allowed-tools: Read, Glob, Grep
+---
+
+# Documentation Templates
+
+> Templates and structure guidelines for common documentation types.
+
+---
+
+## 1. README Structure
+
+### Essential Sections (Priority Order)
+
+| Section | Purpose |
+|---------|---------|
+| **Title + One-liner** | What is this? |
+| **Quick Start** | Running in <5 min |
+| **Features** | What can I do? |
+| **Configuration** | How to customize |
+| **API Reference** | Link to detailed docs |
+| **Contributing** | How to help |
+| **License** | Legal |
+
+### README Template
+
+```markdown
+# Project Name
+
+Brief one-line description.
+
+## Quick Start
+
+[Minimum steps to run]
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 3000 |
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Architecture](./docs/architecture.md)
+
+## License
+
+MIT
+```
+
+---
+
+## 2. API Documentation Structure
+
+### Per-Endpoint Template
+
+```markdown
+## GET /users/:id
+
+Get a user by ID.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | User ID |
+
+**Response:**
+- 200: User object
+- 404: User not found
+
+**Example:**
+[Request and response example]
+```
+
+---
+
+## 3. Code Comment Guidelines
+
+### JSDoc/TSDoc Template
+
+```typescript
+/**
+ * Brief description of what the function does.
+ * 
+ * @param paramName - Description of parameter
+ * @returns Description of return value
+ * @throws ErrorType - When this error occurs
+ * 
+ * @example
+ * const result = functionName(input);
+ */
+```
+
+### When to Comment
+
+| ✅ Comment | ❌ Don't Comment |
+|-----------|-----------------|
+| Why (business logic) | What (obvious) |
+| Complex algorithms | Every line |
+| Non-obvious behavior | Self-explanatory code |
+| API contracts | Implementation details |
+
+---
+
+## 4. Changelog Template (Keep a Changelog)
+
+```markdown
+# Changelog
+
+## [Unreleased]
+### Added
+- New feature
+
+## [1.0.0] - 2025-01-01
+### Added
+- Initial release
+### Changed
+- Updated dependency
+### Fixed
+- Bug fix
+```
+
+---
+
+## 5. Architecture Decision Record (ADR)
+
+```markdown
+# ADR-001: [Title]
+
+## Status
+Accepted / Deprecated / Superseded
+
+## Context
+Why are we making this decision?
+
+## Decision
+What did we decide?
+
+## Consequences
+What are the trade-offs?
+```
+
+---
+
+## 6. AI-Friendly Documentation (2025)
+
+### llms.txt Template
+
+For AI crawlers and agents:
+
+```markdown
+# Project Name
+> One-line objective.
+
+## Core Files
+- [src/index.ts]: Main entry
+- [src/api/]: API routes
+- [docs/]: Documentation
+
+## Key Concepts
+- Concept 1: Brief explanation
+- Concept 2: Brief explanation
+```
+
+### MCP-Ready Documentation
+
+For RAG indexing:
+- Clear H1-H3 hierarchy
+- JSON/YAML examples for data structures
+- Mermaid diagrams for flows
+- Self-contained sections
+
+---
+
+## 7. Structure Principles
+
+| Principle | Why |
+|-----------|-----|
+| **Scannable** | Headers, lists, tables |
+| **Examples first** | Show, don't just tell |
+| **Progressive detail** | Simple → Complex |
+| **Up to date** | Outdated = misleading |
+
+---
+
+> **Remember:** Templates are starting points. Adapt to your project's needs.