@jhm1909/ag-kit 0.1.0

package/.agent/ARCHITECTURE.md

@@ -0,0 +1,189 @@
+# Antigravity Kit Architecture
+
+> **ag-kit** — Modular AI Agent Capability Expansion Toolkit
+
+---
+
+## Overview
+
+Antigravity Kit is a multi-layer system:
+
+```
+USER → /guide (Layer 1: Discovery)
+  → Workflow Chain (Layer 2: Orchestration)
+    → Invoke [skill] (Layer 3: Expertise)
+      → Manifest (Layer 4: Routing)
+        → Rules (Layer 5: Guardrails)
+```
+
+**Philosophy**: Friendly for beginners (guided workflows), powerful for experts (direct skill invocation).
+
+---
+
+## Directory Structure
+
+```
+.agent/
+├── ARCHITECTURE.md           # This file
+├── skills-manifest.json      # Single source of truth (v3.0)
+├── known-registries.json     # External skill registries
+├── mcp_config.json           # MCP server template
+├── skills/                   # 20 Skills + sub-skills
+│   ├── ai-engineer/
+│   ├── app-builder/
+│   ├── backend-developer/
+│   ├── blockchain-engineer/
+│   ├── business-analysis/
+│   ├── code-review/          # v2 — Trail of Bits security methodology
+│   ├── context-engineering/
+│   ├── debugging/
+│   ├── designer/
+│   ├── devops-engineer/
+│   ├── frontend-developer/   # v4 — Vercel React rules
+│   │   ├── react-nextjs/
+│   │   ├── threejs/
+│   │   └── references/       # react_performance_rules, composition_patterns
+│   ├── game-development/
+│   ├── lead-architect/
+│   ├── marketer/
+│   │   └── remotion-best-practices/
+│   ├── mobile-developer/
+│   │   ├── api-routes/
+│   │   ├── building-ui/
+│   │   ├── data-fetching/
+│   │   ├── deployment/
+│   │   ├── dev-client/
+│   │   ├── tailwind-setup/
+│   │   ├── upgrading-expo/
+│   │   └── use-dom/
+│   ├── modern-python/        # Trail of Bits toolchain
+│   ├── project-manager/      # v5 — Dean Peters frameworks
+│   │   └── references/       # discovery_process, prd_development, jobs_to_be_done
+│   ├── prompt-engineer/
+│   ├── qa-tester/            # v3 — Trail of Bits security audit
+│   │   └── references/       # security_audit, supply_chain, PBT, etc.
+│   └── research-first/
+├── workflows/                # 15 Workflows
+│   ├── guide.md              # 🧭 Discovery
+│   ├── brainstorm.md         # 💡 Planning
+│   ├── documentation.md      # 📚 Specs
+│   ├── break-tasks.md        # 📋 Task breakdown
+│   ├── implement-feature.md  # 🔨 Coding
+│   ├── development.md        # 🐛 Quick fixes
+│   ├── debug.md              # 🔬 Scientific debugging
+│   ├── ui-ux-design.md       # 🎨 Design
+│   ├── qa.md                 # 🧪 Test plans
+│   ├── gen-tests.md          # ✅ Test code
+│   ├── absorb.md             # 🔍 Study reference kits
+│   ├── commit.md             # 📦 Git (3-mode)
+│   ├── bootstrap.md          # 🚀 Project scaffolding
+│   ├── install-skill.md      # 📥 On-demand skill installer
+│   └── custom-behavior.md    # ⚙️ Meta-config
+├── rules/                    # 10 Always-on Rules
+│   ├── clean-code.md
+│   ├── documents.md          # Dewey Decimal doc structure
+│   ├── git-workflow.md
+│   ├── nano-banana.md        # Image generation convention
+│   ├── research.md
+│   ├── skill-loading.md      # Skill activation protocol
+│   ├── skill-suggestion.md   # Auto-suggest skills
+│   ├── testing.md
+│   ├── workflow-advisor.md   # Auto-suggest workflow chains
+│   └── workflow-skill-convention.md  # Layer architecture
+└── tmp/                      # Temporary files (gitignored)
+```
+
+---
+
+## Skills (20 primary + sub-skills)
+
+| Skill | Domain | Version | Sources |
+|-------|--------|---------|---------|
+| `project-manager` | management | v5.0 | Dean Peters PM frameworks |
+| `business-analysis` | analysis | — | — |
+| `qa-tester` | qa | v3.0 | Trail of Bits security |
+| `code-review` | qa | v2.0 | Trail of Bits differential review |
+| `frontend-developer` | web | v4.0 | Vercel React rules |
+| `backend-developer` | infra | — | — |
+| `mobile-developer` | mobile | — | — |
+| `designer` | design | — | — |
+| `devops-engineer` | infra | — | — |
+| `lead-architect` | infra | — | — |
+| `ai-engineer` | ai | — | — |
+| `blockchain-engineer` | blockchain | — | — |
+| `marketer` | marketing | — | — |
+| `prompt-engineer` | ai | — | — |
+| `app-builder` | meta | — | — |
+| `game-development` | game | — | — |
+| `context-engineering` | meta | — | — |
+| `debugging` | qa | — | — |
+| `research-first` | meta | — | — |
+| `modern-python` | tooling | v1.0 | Trail of Bits uv/ruff/ty |
+
+---
+
+## Workflows (15)
+
+### Workflow Chains
+
+```
+New Project:    /brainstorm → /documentation → /break-tasks → /implement-feature → /commit
+New Feature:    /break-tasks → /implement-feature → /gen-tests → /commit
+Bug Fix:        /development → /gen-tests → /commit
+Debug:          /debug → /commit
+UI/UX:          /ui-ux-design → /break-tasks → /implement-feature → /commit
+Study Kit:      /absorb → /break-tasks → /implement-feature → /commit
+MVP Sprint:     /brainstorm → /documentation → [/break-tasks → /implement-feature → /commit] × N
+```
+
+### Commit Modes
+
+| Mode | Branch | Diff | .gitignore | Protected | Message | Push |
+|------|--------|------|------------|-----------|---------|------|
+| ⚡ Quick | skip | brief | skip | skip | auto | auto |
+| 🛡️ Safe | check | full | auto-fix | confirm | approve | auto |
+| 🎛️ Custom | ask | full | ask | list all | edit | ask |
+
+---
+
+## Rules (10)
+
+| Rule | Purpose |
+|------|---------|
+| `clean-code` | Coding standards |
+| `documents` | Dewey Decimal doc structure |
+| `git-workflow` | Branch strategy, commit format |
+| `nano-banana` | Image generation convention |
+| `research` | Deep research protocol |
+| `skill-loading` | Skill activation routing |
+| `skill-suggestion` | Auto-suggest relevant skills |
+| `testing` | Test coverage requirements |
+| `workflow-advisor` | Auto-suggest workflow chains |
+| `workflow-skill-convention` | 5-layer architecture enforcement |
+
+---
+
+## Profiles
+
+Pre-configured skill bundles (via `ag-kit init --profile`):
+
+| Profile | Skills | Optional |
+|---------|--------|----------|
+| `web-frontend` | frontend, designer | react-nextjs, threejs |
+| `fullstack-saas` | frontend, backend, devops, PM, QA | react-nextjs, ai-engineer |
+| `mobile-app` | mobile, designer, QA | backend |
+| `video-content` | marketer, frontend, remotion | threejs |
+| `ai-powered-app` | ai-engineer, frontend, backend | lead-architect |
+| `blockchain-dapp` | blockchain, frontend, backend | devops |
+
+---
+
+## Statistics
+
+| Metric | Count |
+|--------|------:|
+| Skills | 20 primary + sub-skills |
+| Workflows | 15 |
+| Rules | 10 |
+| Profiles | 6 |
+| Absorbed Sources | Trail of Bits, Vercel, Dean Peters |

package/.agent/known-registries.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "Curated registry of trusted skill sources for /install-skill workflow",
+  "version": "1.0.0",
+  "updated": "2026-03-27",
+  "registries": [
+    {
+      "id": "anthropic-official",
+      "org": "anthropics",
+      "repo": "skills",
+      "url": "https://github.com/anthropics/skills",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "frontend-design", "description": "Frontend design and UI/UX development" },
+        { "name": "mcp-builder", "description": "Create MCP servers for external APIs" },
+        { "name": "webapp-testing", "description": "Test web apps using Playwright" },
+        { "name": "skill-creator", "description": "Guide for creating new skills" },
+        { "name": "docx", "description": "Create, edit, analyze Word documents" },
+        { "name": "pdf", "description": "Extract text, create PDFs, handle forms" },
+        { "name": "xlsx", "description": "Create, edit, analyze Excel spreadsheets" }
+      ]
+    },
+    {
+      "id": "vercel-engineering",
+      "org": "vercel-labs",
+      "repo": "agent-skills",
+      "url": "https://github.com/vercel-labs/agent-skills",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "react-best-practices", "description": "65+ React optimization rules from Vercel" },
+        { "name": "web-design-guidelines", "description": "Web design standards and guidelines" },
+        { "name": "composition-patterns", "description": "React component composition patterns" }
+      ]
+    },
+    {
+      "id": "vercel-next",
+      "org": "vercel-labs",
+      "repo": "next-skills",
+      "url": "https://github.com/vercel-labs/next-skills",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "next-best-practices", "description": "Next.js best practices and patterns" },
+        { "name": "next-cache-components", "description": "Caching strategies in Next.js" },
+        { "name": "next-upgrade", "description": "Upgrade Next.js projects" }
+      ]
+    },
+    {
+      "id": "stripe",
+      "org": "stripe",
+      "repo": "ai",
+      "url": "https://github.com/stripe/ai",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "stripe-best-practices", "description": "Best practices for Stripe integrations" },
+        { "name": "upgrade-stripe", "description": "Upgrade Stripe SDK and API versions" }
+      ]
+    },
+    {
+      "id": "cloudflare",
+      "org": "cloudflare",
+      "repo": "skills",
+      "url": "https://github.com/cloudflare/skills",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "agents-sdk", "description": "Build stateful AI agents on Cloudflare" },
+        { "name": "building-mcp-server-on-cloudflare", "description": "Build remote MCP servers" },
+        { "name": "durable-objects", "description": "Stateful coordination with RPC and SQLite" },
+        { "name": "web-perf", "description": "Audit Core Web Vitals" },
+        { "name": "wrangler", "description": "Deploy Workers, KV, R2, D1, Queues" }
+      ]
+    },
+    {
+      "id": "trailofbits-security",
+      "org": "trailofbits",
+      "repo": "skills",
+      "url": "https://github.com/trailofbits/skills",
+      "trust": "official",
+      "skills_path": "plugins/",
+      "skills": [
+        { "name": "static-analysis", "description": "CodeQL, Semgrep, and SARIF toolkit" },
+        { "name": "semgrep-rule-creator", "description": "Create Semgrep vulnerability rules" },
+        { "name": "differential-review", "description": "Security-focused diff review" },
+        { "name": "property-based-testing", "description": "Property testing for multiple languages" },
+        { "name": "modern-python", "description": "Modern Python: uv, ruff, ty, pytest" },
+        { "name": "insecure-defaults", "description": "Detect hardcoded secrets, weak crypto" }
+      ]
+    },
+    {
+      "id": "sentry",
+      "org": "getsentry",
+      "repo": "skills",
+      "url": "https://github.com/getsentry/skills",
+      "trust": "official",
+      "skills_path": "plugins/sentry-skills/skills/",
+      "skills": [
+        { "name": "code-review", "description": "Sentry's code review workflow" },
+        { "name": "find-bugs", "description": "Find and identify bugs in code" },
+        { "name": "create-pr", "description": "Create pull requests" },
+        { "name": "commit", "description": "Create commits with best practices" }
+      ]
+    },
+    {
+      "id": "openai",
+      "org": "openai",
+      "repo": "skills",
+      "url": "https://github.com/openai/skills",
+      "trust": "official",
+      "skills_path": "skills/.curated/",
+      "skills": [
+        { "name": "security-best-practices", "description": "Language-specific security review" },
+        { "name": "security-threat-model", "description": "Generate repo-specific threat models" },
+        { "name": "playwright", "description": "Browser automation for testing" },
+        { "name": "jupyter-notebook", "description": "Clean, reproducible Jupyter notebooks" }
+      ]
+    },
+    {
+      "id": "supabase",
+      "org": "supabase",
+      "repo": "agent-skills",
+      "url": "https://github.com/supabase/agent-skills",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "supabase-postgres-best-practices", "description": "PostgreSQL best practices for Supabase" }
+      ]
+    },
+    {
+      "id": "google-gemini",
+      "org": "google-gemini",
+      "repo": "gemini-skills",
+      "url": "https://github.com/google-gemini/gemini-skills",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "gemini-api-dev", "description": "Best practices for Gemini API apps" },
+        { "name": "gemini-live-api-dev", "description": "Real-time streaming with Gemini Live API" }
+      ]
+    },
+    {
+      "id": "expo",
+      "org": "expo",
+      "repo": "skills",
+      "url": "https://github.com/expo/skills",
+      "trust": "official",
+      "skills_path": "plugins/expo/skills/",
+      "skills": [
+        { "name": "building-native-ui", "description": "Expo Router, styling, animations" },
+        { "name": "native-data-fetching", "description": "Network requests, caching, offline" }
+      ]
+    },
+    {
+      "id": "huggingface",
+      "org": "huggingface",
+      "repo": "skills",
+      "url": "https://github.com/huggingface/skills",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "huggingface-gradio", "description": "Build Gradio apps on HF Spaces" },
+        { "name": "transformers.js", "description": "Run ML models in the browser" },
+        { "name": "hugging-face-model-trainer", "description": "Train models with TRL: SFT, DPO, GRPO" }
+      ]
+    },
+    {
+      "id": "figma",
+      "org": "figma",
+      "repo": "mcp-server-guide",
+      "url": "https://github.com/figma/mcp-server-guide",
+      "trust": "official",
+      "skills_path": "skills/",
+      "skills": [
+        { "name": "figma-implement-design", "description": "Figma design to production code" },
+        { "name": "figma-generate-design", "description": "Build screens in Figma from code" }
+      ]
+    }
+  ]
+}

package/.agent/mcp_config.json

@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+      }
+    }
+  }
+}

package/.agent/rules/clean-code.md

@@ -0,0 +1,107 @@
+---
+trigger: glob
+globs: **/*.{ts,tsx,js,jsx,py,go,java,rb,c,cpp,h,hpp,rs,css,html}
+---
+
+# Clean Code Standards
+
+## Core Principles
+
+- **SOLID**: Follow Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion principles.
+- **DRY (Don't Repeat Yourself)**: Extract common logic into functions or constants.
+- **KISS (Keep It Simple, Stupid)**: Avoid over-engineering. Code should be easy to understand.
+- **YAGNI (You Aren't Gonna Need It)**: Do not implement features or abstraction "just in case".
+
+## Naming Conventions
+
+- Variables and functions should be descriptive (e.g., `isUserLoggedIn` instead of `flag`).
+- Use consistent casing appropriate for the language (e.g., camelCase for JS/TS functions, snake_case for Python).
+- Boolean variables should start with `is`, `has`, `should`, or `can`.
+
+## Functions
+
+- Functions should ideally do one thing and do it well.
+- Keep functions short. If a function is too long, break it down.
+- Limit the number of arguments (3 or fewer is ideal).
+
+## Comments
+
+- Comments should explain "why" something is done, not "what" the code does (unless it's complex/unintuitive).
+- Remove commented-out code.
+
+## Error Handling
+
+- Context-aware error handling. Do not silently swallow errors.
+- Use explicit error types where possible.
+
+## Testing
+
+- Write testable code. Avoid global state and side effects where possible.
+
+## File Length Limits
+
+Files should be kept concise and focused. If a file exceeds these limits, consider splitting it:
+
+| File Type                   | Max Lines | Notes                                          |
+| --------------------------- | --------- | ---------------------------------------------- |
+| Components (`.tsx`, `.jsx`) | 200-300   | Split into smaller components or extract hooks |
+| Utility/Helper files        | 150-200   | Group related utilities, split by domain       |
+| API Routes/Handlers         | 100-150   | Extract business logic to services             |
+| Test files                  | 300-400   | Group by feature, use describe blocks          |
+| Styles (`.css`)             | 200-300   | Use CSS modules or split by component          |
+| Config files                | 100       | Keep minimal, use separate config files        |
+
+**When to split:**
+
+- When a file has multiple responsibilities (violates SRP)
+- When scrolling becomes difficult to follow logic
+- When imports section becomes excessively long (>15 imports)
+- When the file has multiple large functions that could be independent
+
+## File Header Comments
+
+Every new file MUST include a header comment at the top describing its purpose:
+
+**Format for TypeScript/JavaScript:**
+
+```typescript
+/**
+ * @file [filename]
+ * @description [Brief description of what this file contains and its purpose]
+ *
+ * @example (optional - for utilities/hooks)
+ * // Usage example here
+ */
+```
+
+**Format for CSS:**
+
+```css
+/**
+ * @file [filename]
+ * @description [Brief description of styles contained]
+ * 
+ * Sections:
+ * - [List main sections if applicable]
+ */
+```
+
+**Format for Python:**
+
+```python
+"""
+[filename]
+
+[Brief description of what this module contains and its purpose]
+
+Example (optional):
+    >>> usage_example()
+"""
+```
+
+**Requirements:**
+
+- `@file`: The filename (e.g., `user.service.ts`)
+- `@description`: 1-3 sentences explaining the file's purpose
+- Keep headers concise but informative
+- Update headers when file purpose changes significantly

package/.agent/rules/documents.md

@@ -0,0 +1,177 @@
+---
+trigger: model_decision
+description: Always apply when working with documentation files
+---
+
+# Documentation Structure Rule
+
+## Critical Rules (MUST Follow)
+
+1. **MUST** save all documents to `docs/` folder - NEVER create documents in project root or other folders
+2. **MUST** use Dewey Decimal folder structure (010, 020, 030, etc.)
+3. **MUST** include YAML frontmatter in every document
+4. **MUST** update relevant MOC file after creating a new document
+5. **MUST** use wiki-links `[[Document-Name]]` for cross-references
+6. **MUST NOT** create custom folder structures like `01-product/`, `02-analysis/`
+7. **MUST NOT** create documents without checking Document Type Mapping first
+
+## Decision Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ BEFORE creating any document, ask yourself:                 │
+├─────────────────────────────────────────────────────────────┤
+│ 1. Does docs/ folder exist?                                 │
+│    NO  → Create folder structure (see Required Structure)   │
+│    YES → Continue                                           │
+├─────────────────────────────────────────────────────────────┤
+│ 2. What type of document is this?                           │
+│    → Look up in Document Type Mapping table                 │
+│    → Get exact target folder and naming convention          │
+├─────────────────────────────────────────────────────────────┤
+│ 3. Does target folder exist?                                │
+│    NO  → Create it with proper Dewey Decimal prefix         │
+│    YES → Continue                                           │
+├─────────────────────────────────────────────────────────────┤
+│ 4. Create document with:                                    │
+│    → Correct naming convention                              │
+│    → Required frontmatter                                   │
+│    → Wiki-links to related documents                        │
+├─────────────────────────────────────────────────────────────┤
+│ 5. AFTER creating document:                                 │
+│    → Update parent folder's MOC file                        │
+│    → Update 000-Index.md if major document                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Document Type Mapping
+
+| Category             | Document Type       | Target Folder                          | Naming Convention          |
+| -------------------- | ------------------- | -------------------------------------- | -------------------------- |
+| **010-Planning**     | Roadmap             | `docs/010-Planning/`                   | `Roadmap.md`               |
+|                      | OKRs                | `docs/010-Planning/`                   | `OKRs.md`                  |
+|                      | Sprint              | `docs/010-Planning/Sprints/`           | `Sprint-{NNN}.md`          |
+| **020-Requirements** | PRD                 | `docs/020-Requirements/`               | `PRD-{ProjectName}.md`     |
+|                      | BRD                 | `docs/020-Requirements/BRD/`           | `BRD-{NNN}-{Title}.md`     |
+|                      | Use Case            | `docs/020-Requirements/Use-Cases/`     | `UC-{NN}-{Title}.md`       |
+| **022-User-Stories** | Epic                | `docs/022-User-Stories/Epics/`         | `Epic-{Title}.md`          |
+|                      | User Story          | `docs/022-User-Stories/Backlog/`       | `Story-{Title}.md`         |
+|                      | Active Story        | `docs/022-User-Stories/Active-Sprint/` | `Story-{Title}.md`         |
+| **030-Specs**        | ADR                 | `docs/030-Specs/Architecture/`         | `ADR-{NNN}-{Title}.md`     |
+|                      | RFC                 | `docs/030-Specs/Architecture/`         | `RFC-{NNN}-{Title}.md`     |
+|                      | SDD (System Design) | `docs/030-Specs/Architecture/`         | `SDD-{ProjectName}.md`     |
+|                      | Technical Spec      | `docs/030-Specs/`                      | `Spec-{Feature}.md`        |
+|                      | API Endpoint Spec   | `docs/030-Specs/API/`                  | `Endpoint-{Name}.md`       |
+|                      | DB Schema           | `docs/030-Specs/Schema/`               | `DB-Entity-{Name}.md`      |
+| **035-QA**           | Test Plan           | `docs/035-QA/Test-Plans/`              | `MTP-{Name}.md`            |
+|                      | Test Case           | `docs/035-QA/Test-Cases/`              | `TC-{Feature}-{NNN}.md`    |
+| **040-Design**       | Design System       | `docs/040-Design/Design-System/`       | `{Component}.md`           |
+|                      | Wireframe           | `docs/040-Design/Wireframes/`          | `WF-{Screen}-{Device}.png` |
+| **050-Research**     | Research/Analysis   | `docs/050-Research/{Topic}/`           | `Analysis-{Topic}.md`      |
+|                      | Absorb Plan         | `docs/050-Research/{SourceName}/`      | `Absorb-{SourceName}.md`   |
+|                      | Research Index      | `docs/050-Research/`                   | `Research-MOC.md`          |
+| **060-Manuals**      | User Guide          | `docs/060-Manuals/User-Guide/`         | `{Topic}.md`               |
+|                      | Admin Guide         | `docs/060-Manuals/Admin-Guide/`        | `{Topic}.md`               |
+| **090-Archive**      | Deprecated Docs     | `docs/090-Archive/`                    | `{Original-Name}.md`       |
+| **999-Resources**    | Meeting Notes       | `docs/999-Resources/Meeting-Notes/`    | `{Type}-{Date}.md`         |
+|                      | Glossary            | `docs/999-Resources/`                  | `Glossary.md`              |
+|                      | Template            | `docs/999-Resources/Templates/`        | `Template-{Type}.md`       |
+
+## Required Folder Structure
+
+```
+docs/
+├── 000-Index.md                        # "Home Page" - MUST exist
+│
+├── 010-Planning/                       # Strategy, Timelines, Roadmaps
+│   ├── Planning-MOC.md                 # REQUIRED MOC
+│   ├── Roadmap.md
+│   ├── OKRs.md
+│   └── Sprints/
+│
+├── 020-Requirements/                   # Business Requirements
+│   ├── Requirements-MOC.md             # REQUIRED MOC
+│   ├── BRD/
+│   └── Use-Cases/
+│
+├── 022-User-Stories/                   # Agile Backlog
+│   ├── Stories-MOC.md                  # REQUIRED MOC
+│   ├── Epics/
+│   ├── Active-Sprint/
+│   └── Backlog/
+│
+├── 030-Specs/                          # Technical Specs
+│   ├── Specs-MOC.md                    # REQUIRED MOC
+│   ├── Architecture/
+│   ├── API/
+│   └── Schema/
+│
+├── 035-QA/                             # Quality Assurance
+│   ├── QA-MOC.md                       # REQUIRED MOC
+│   ├── Test-Plans/
+│   ├── Test-Cases/
+│   ├── Automation/
+│   ├── Reports/
+│   └── Performance/
+│
+├── 040-Design/                         # UI/UX & Frontend
+│   ├── Design-MOC.md                   # REQUIRED MOC
+│   ├── Wireframes/
+│   ├── Design-System/
+│   ├── Specs/
+│   └── Assets/
+│
+├── 050-Research/                       # Discovery & Analysis
+│   ├── Research-MOC.md                 # REQUIRED MOC
+│   ├── Competitor-Analysis/
+│   └── User-Interviews/
+│
+├── 060-Manuals/                        # End-User Documentation
+│   ├── Manuals-MOC.md                  # REQUIRED MOC
+│   ├── User-Guide/
+│   └── Admin-Guide/
+│
+├── 090-Archive/                        # Deprecated docs (never delete)
+│
+└── 999-Resources/                      # Templates, Scripts, Glossary
+    ├── Templates/
+    ├── Glossary.md
+    └── Meeting-Notes/
+```
+
+## Frontmatter Template
+
+Every document MUST include this frontmatter:
+
+```yaml
+---
+id: {TYPE}-{NNN}           # Unique identifier (e.g., PRD-001, UC-01)
+type: {document_type}      # prd, brd, use-case, epic, story, spec, adr, etc.
+status: draft|review|approved|deprecated
+project: {project_name}    # Optional: for multi-project docs
+owner: "@{team_or_person}" # Optional: responsible party
+tags: [tag1, tag2]         # Optional: for search/filtering
+linked-to: [[Related-Doc]] # Optional: primary relationship
+created: YYYY-MM-DD
+updated: YYYY-MM-DD        # Optional: last update date
+---
+```
+
+## Linking Rules
+
+1. **PRD** → links to Epics it spawns: `## Related Epics\n- [[Epic-Feature1]]\n- [[Epic-Feature2]]`
+2. **Epic** → links to parent PRD: `Implements: [[PRD-ProjectName]]`
+3. **Use Case** → links to Epic: `Part of: [[Epic-Feature]]`
+4. **SDD** → links to PRD: `Implements: [[PRD-ProjectName]]`
+5. **ADR** → links to SDD: `Related to: [[SDD-ProjectName]]`
+
+## Validation Checklist
+
+Before finalizing any document, verify:
+
+- [ ] Document is in correct `docs/XXX-Category/` folder
+- [ ] Filename follows naming convention from mapping table
+- [ ] Frontmatter includes required fields (id, type, status, created)
+- [ ] Wiki-links to related documents are added
+- [ ] Parent folder's MOC file is updated with link to new document
+- [ ] 000-Index.md updated (for major documents like PRD, SDD)