@yan-geroge/omg 0.1.0

package/.claude/skills/trellis-spec-bootstarp/references/mcp-setup.md

@@ -0,0 +1,90 @@
+# MCP Setup
+
+GitNexus and ABCoder are recommended when bootstrapping Trellis specs because they expose architecture and AST context to the agent. They are tool choices, not platform requirements. Configure them through whatever MCP mechanism your agent host provides.
+
+## GitNexus
+
+GitNexus builds a code knowledge graph from the repository. Use it for module boundaries, execution flows, dependency relationships, blast radius, and graph queries.
+
+### Install and Index
+
+```bash
+# Run from the repository root.
+npx gitnexus analyze
+
+# Check index status.
+npx gitnexus status
+
+# Re-index after code changes when the analysis is stale.
+npx gitnexus analyze
+```
+
+The index is written to `.gitnexus/`. Keep embeddings only if the project already uses them; otherwise a normal index is enough for spec bootstrapping.
+
+### MCP Server Command
+
+Use this server command in the host's MCP configuration:
+
+```bash
+npx -y gitnexus mcp
+```
+
+### Useful Tools
+
+| Tool | Purpose |
+|------|---------|
+| `gitnexus_query` | Find execution flows and functional areas by concept |
+| `gitnexus_context` | Inspect callers, callees, references, and process participation for a symbol |
+| `gitnexus_impact` | Understand blast radius before changing a symbol |
+| `gitnexus_detect_changes` | Check changed symbols and affected flows before finishing |
+| `gitnexus_cypher` | Run direct graph queries |
+| `gitnexus_list_repos` | List indexed repositories |
+
+## ABCoder
+
+ABCoder parses code into UniAST and gives precise package, file, and node-level structure. Use it for signatures, type shapes, implementations, dependencies, and reverse references.
+
+### Install
+
+```bash
+go install github.com/cloudwego/abcoder@latest
+abcoder --help
+```
+
+### Parse Repositories
+
+```bash
+abcoder parse /absolute/path/to/package \
+  --lang typescript \
+  --name package-name \
+  --output ~/abcoder-asts
+```
+
+For monorepos, parse each package with a stable `--name` so task notes can reference the same repository names.
+
+### MCP Server Command
+
+Use this server command in the host's MCP configuration:
+
+```bash
+abcoder mcp ~/abcoder-asts
+```
+
+### Useful Tools
+
+| Tool | Layer | Purpose |
+|------|-------|---------|
+| `list_repos` | 1 | List parsed repositories |
+| `get_repo_structure` | 2 | Inspect packages and files |
+| `get_package_structure` | 3 | Inspect nodes within a package |
+| `get_file_structure` | 3 | Inspect functions, classes, types, and signatures in a file |
+| `get_ast_node` | 4 | Retrieve code, dependencies, references, and implementations |
+
+## Verification
+
+After configuration, verify from the agent host that both MCP servers are visible. Then run one simple query against each server before starting the spec writing pass.
+
+```bash
+ls .gitnexus/meta.json
+ls ~/abcoder-asts/*.json
+```

package/.claude/skills/trellis-spec-bootstarp/references/repository-analysis.md

@@ -0,0 +1,59 @@
+# Repository Analysis
+
+The goal is to discover the project's real architecture before writing rules. Do not start from generic spec templates and fill blanks. Start from the code, then let the spec structure follow.
+
+## Analysis Order
+
+1. Read the existing `.trellis/spec/` tree and note which files are templates, outdated, or already project-specific.
+2. Inspect package manifests, build scripts, workspace config, and top-level documentation to identify packages and runtime layers.
+3. Use GitNexus for execution flows, module clusters, dependency hubs, and impact-sensitive areas.
+4. Use ABCoder or language-native tooling for exact signatures, types, class boundaries, and implementation examples.
+5. Read representative source and test files directly before turning any finding into a spec rule.
+
+## What To Capture
+
+| Area | Questions |
+|------|-----------|
+| Package boundaries | What does each package own? What imports cross boundaries? |
+| Runtime layers | Which code is CLI, backend, frontend, worker, shared library, test-only, or tooling? |
+| Core abstractions | Which types, services, stores, commands, routes, or adapters define the system shape? |
+| Data flow | Where does user input enter, how is it validated, and where does state persist? |
+| Error handling | How are failures represented, logged, surfaced, and tested? |
+| Configuration | Where do defaults, environment config, generated files, and templates live? |
+| Tests | Which test styles are trusted examples for new work? |
+
+## GitNexus Usage
+
+Start broad, then inspect specific symbols:
+
+```text
+gitnexus_query({query: "CLI command execution flow"})
+gitnexus_query({query: "template generation and migration"})
+gitnexus_context({name: "SymbolName"})
+gitnexus_cypher({query: "MATCH (n)-[r]->(m) RETURN n.name, type(r), m.name LIMIT 30"})
+```
+
+Use GitNexus results to find important files and flows. Do not quote graph output as the final authority until you have checked the relevant source files.
+
+## ABCoder Usage
+
+Use ABCoder when the spec needs exact code shapes:
+
+```text
+list_repos()
+get_repo_structure({repo_name: "package-name"})
+get_file_structure({repo_name: "package-name", file_path: "src/example.ts"})
+get_ast_node({repo_name: "package-name", node_ids: [{mod_path: "...", pkg_path: "...", name: "SymbolName"}]})
+```
+
+ABCoder is most valuable for documenting constructor patterns, function signatures, type contracts, and reference chains.
+
+## Analysis Notes
+
+Keep short notes while analyzing. The notes should include:
+
+- Package or layer name.
+- Files that define the local pattern.
+- Rules the spec should teach.
+- Anti-patterns found in old code, comments, tests, or migration paths.
+- Spec files that should be created, deleted, renamed, or merged.

package/.claude/skills/trellis-spec-bootstarp/references/spec-task-planning.md

@@ -0,0 +1,61 @@
+# Spec Task Planning
+
+Use a single agent as the default execution model. The agent may create Trellis tasks for traceability, but the skill should not require a specific platform, CLI, or parallel worker model.
+
+## Decomposition
+
+Create spec work units around real ownership boundaries:
+
+- One package when a package has its own conventions.
+- One layer when the same package has distinct frontend, backend, CLI, worker, or shared-library rules.
+- One cross-cutting guide when a pattern spans packages and is not owned by one layer.
+
+Avoid artificial decomposition. A small library usually needs one focused spec pass, not several tasks.
+
+## Task Shape
+
+When a Trellis task is useful, write a concise PRD with these sections:
+
+```markdown
+# Fill <package-or-layer> Trellis Specs
+
+## Goal
+Write project-specific `.trellis/spec/` guidance for <scope>.
+
+## Scope
+- Spec directory:
+- Source directories to inspect:
+- Tests to inspect:
+- Out of scope:
+
+## Architecture Context
+Summarize the concrete findings from repository analysis.
+
+## Files To Create Or Update
+- `.trellis/spec/.../index.md`
+- `.trellis/spec/.../<topic>.md`
+
+## Rules
+- Adapt the spec file set to the real codebase.
+- Use real source examples with file paths.
+- Remove template-only sections that do not apply.
+- Do not modify product source code unless the task explicitly asks for it.
+
+## Acceptance Criteria
+- [ ] Specs contain concrete examples and anti-patterns from the repository.
+- [ ] No placeholder text remains.
+- [ ] Index files match the final spec files.
+- [ ] Claims are backed by source files, tests, or project docs.
+```
+
+## Optional Helper Agents
+
+If the host supports subagents, helpers can inspect independent packages or run verification. They are optional. The main agent still owns integration and final quality.
+
+Helper tasks must have clear ownership:
+
+- Read-only research tasks may inspect any source needed for the assigned scope.
+- Write tasks should own disjoint spec directories.
+- Verification tasks should check placeholder removal, broken links, and consistency.
+
+Do not encode helper-agent names, vendor-specific commands, or platform-specific routing in the skill. Put only the required work and acceptance criteria in the task.

package/.claude/skills/trellis-spec-bootstarp/references/spec-writing.md

@@ -0,0 +1,70 @@
+# Spec Writing
+
+Trellis specs are coding guidance for future agents. They should explain how to work in this repository, not how a generic project might be organized.
+
+## Write From Evidence
+
+Each important rule should be backed by one of these:
+
+- A source file that demonstrates the preferred pattern.
+- A test file that shows expected behavior.
+- A project document that defines the convention.
+- A repeated pattern across multiple files.
+
+Use short snippets only when they make the rule clearer. Prefer linking to the file path and naming the symbol or behavior.
+
+## File Structure
+
+Keep the spec tree aligned with the project:
+
+- Keep `index.md` as the navigation file for the spec directory.
+- Split topics when developers would look for them independently.
+- Merge topics when separate files would repeat the same rule.
+- Delete template files that do not apply.
+- Add new files for important local patterns the template missed.
+
+## Content Standards
+
+Good spec sections include:
+
+- When the rule applies.
+- The local pattern to follow.
+- The source or test files that prove the pattern.
+- Common mistakes or anti-patterns.
+- Verification commands or checks when they are specific and reliable.
+
+Avoid:
+
+- Placeholder prose.
+- Generic framework advice.
+- Tool instructions that only work in one agent host.
+- Long copied code blocks.
+- Rules based on a single accidental implementation detail.
+
+## Example Shape
+
+```markdown
+## Command Handlers
+
+Command handlers should keep argument parsing, validation, and side effects separate. The local pattern is:
+
+- Parse CLI flags at the command boundary.
+- Convert raw inputs into typed task options before invoking core logic.
+- Keep filesystem writes in the command or service layer, not in template helpers.
+
+Reference files:
+- `packages/cli/src/commands/example.ts`
+- `packages/cli/test/commands/example.test.ts`
+
+Avoid passing raw `process.argv` or unvalidated config objects into shared helpers.
+```
+
+## Final Pass
+
+Before finishing:
+
+```bash
+grep -R "To be filled\\|TODO: fill\\|placeholder" .trellis/spec
+```
+
+Also check links, index files, and whether any spec still describes a template rather than this repository.

package/.claude/skills/trellis-update-spec/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: trellis-update-spec
+description: "Captures executable contracts and coding conventions into .trellis/spec/ documents. Use when learning something valuable from debugging, implementing, or discussion that should be preserved for future sessions."
+---
+
+# Update Code-Spec - Capture Executable Contracts
+
+When you learn something valuable (from debugging, implementing, or discussion), use this to update the relevant code-spec documents.
+
+**Timing**: After completing a task, fixing a bug, or discovering a new pattern
+
+---
+
+## Code-Spec First Rule (CRITICAL)
+
+In this project, "spec" for implementation work means **code-spec**:
+- Executable contracts (not principle-only text)
+- Concrete signatures, payload fields, env keys, and boundary behavior
+- Testable validation/error behavior
+
+If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
+
+### Mandatory Triggers
+
+Apply code-spec depth when the change includes any of:
+- New/changed command or API signature
+- Cross-layer request/response contract change
+- Database schema/migration change
+- Infra integration (storage, queue, cache, secrets, env wiring)
+
+### Mandatory Output (7 Sections)
+
+For triggered tasks, include all sections below:
+1. Scope / Trigger
+2. Signatures (command/API/DB)
+3. Contracts (request/response/env)
+4. Validation & Error Matrix
+5. Good/Base/Bad Cases
+6. Tests Required (with assertion points)
+7. Wrong vs Correct (at least one pair)
+
+---
+
+## When to Update Code-Specs
+
+| Trigger | Example | Target Spec |
+|---------|---------|-------------|
+| **Implemented a feature** | Added a new integration or module | Relevant spec file |
+| **Made a design decision** | Chose extensibility pattern over simplicity | Relevant spec + "Design Decisions" section |
+| **Fixed a bug** | Found a subtle issue with error handling | Relevant spec (e.g., error-handling docs) |
+| **Discovered a pattern** | Found a better way to structure code | Relevant spec file |
+| **Hit a gotcha** | Learned that X must be done before Y | Relevant spec + "Common Mistakes" section |
+| **Established a convention** | Team agreed on naming pattern | Quality guidelines |
+| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item) |
+
+**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.
+
+---
+
+## Spec Structure Overview
+
+```
+.trellis/spec/
+├── <layer>/           # Per-layer coding standards (e.g., backend/, frontend/, api/)
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+└── guides/            # Thinking checklists (NOT coding specs!)
+    ├── index.md       # Guide index
+    └── *.md           # Topic-specific guides
+```
+
+### CRITICAL: Code-Spec vs Guide - Know the Difference
+
+| Type | Location | Purpose | Content Style |
+|------|----------|---------|---------------|
+| **Code-Spec** | `<layer>/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points |
+| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
+
+**Decision Rule**: Ask yourself:
+
+- "This is **how to write** the code" → Put in a spec layer directory
+- "This is **what to consider** before writing" → Put in `guides/`
+
+**Example**:
+
+| Learning | Wrong Location | Correct Location |
+|----------|----------------|------------------|
+| "Use API X not API Y for this task" | ❌ `guides/` (too specific for a thinking guide) | ✅ Relevant spec file (concrete convention) |
+| "Remember to check X when doing Y" | ❌ Spec file (too abstract for a spec) | ✅ `guides/` (thinking checklist) |
+
+**Guides should be short checklists that point to specs**, not duplicate the detailed rules.
+
+---
+
+## Update Process
+
+### Step 1: Identify What You Learned
+
+Answer these questions:
+
+1. **What did you learn?** (Be specific)
+2. **Why is it important?** (What problem does it prevent?)
+3. **Where does it belong?** (Which spec file?)
+
+### Step 2: Classify the Update Type
+
+| Type | Description | Action |
+|------|-------------|--------|
+| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
+| **Project Convention** | How we do X in this project | Add to relevant section with examples |
+| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
+| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
+| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
+| **Convention** | Agreed-upon standard | Add to relevant section |
+| **Gotcha** | Non-obvious behavior | Add warning callout |
+
+### Step 3: Read the Target Code-Spec
+
+Before editing, read the current code-spec to:
+- Understand existing structure
+- Avoid duplicating content
+- Find the right section for your update
+
+```bash
+cat .trellis/spec/<category>/<file>.md
+```
+
+### Step 4: Make the Update
+
+Follow these principles:
+
+1. **Be Specific**: Include concrete examples, not just abstract rules
+2. **Explain Why**: State the problem this prevents
+3. **Show Contracts**: Add signatures, payload fields, and error behavior
+4. **Show Code**: Add code snippets for key patterns
+5. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the code-spec status changed, update the category's `index.md`.
+
+---
+
+## Update Templates
+
+### Mandatory Template for Infra/Cross-Layer Work
+
+```markdown
+## Scenario: <name>
+
+### 1. Scope / Trigger
+- Trigger: <why this requires code-spec depth>
+
+### 2. Signatures
+- Backend command/API/DB signature(s)
+
+### 3. Contracts
+- Request fields (name, type, constraints)
+- Response fields (name, type, constraints)
+- Environment keys (required/optional)
+
+### 4. Validation & Error Matrix
+- <condition> -> <error>
+
+### 5. Good/Base/Bad Cases
+- Good: ...
+- Base: ...
+- Bad: ...
+
+### 6. Tests Required
+- Unit/Integration/E2E with assertion points
+
+### 7. Wrong vs Correct
+#### Wrong
+...
+#### Correct
+...
+```
+
+### Adding a Design Decision
+
+```markdown
+### Design Decision: [Decision Name]
+
+**Context**: What problem were we solving?
+
+**Options Considered**:
+1. Option A - brief description
+2. Option B - brief description
+
+**Decision**: We chose Option X because...
+
+**Example**:
+\`\`\`typescript
+// How it's implemented
+code example
+\`\`\`
+
+**Extensibility**: How to extend this in the future...
+```
+
+### Adding a Project Convention
+
+```markdown
+### Convention: [Convention Name]
+
+**What**: Brief description of the convention.
+
+**Why**: Why we do it this way in this project.
+
+**Example**:
+\`\`\`typescript
+// How to follow this convention
+code example
+\`\`\`
+
+**Related**: Links to related conventions or specs.
+```
+
+### Adding a New Pattern
+
+```markdown
+### Pattern Name
+
+**Problem**: What problem does this solve?
+
+**Solution**: Brief description of the approach.
+
+**Example**:
+\`\`\`
+// Good
+code example
+
+// Bad
+code example
+\`\`\`
+
+**Why**: Explanation of why this works better.
+```
+
+### Adding a Forbidden Pattern
+
+```markdown
+### Don't: Pattern Name
+
+**Problem**:
+\`\`\`
+// Don't do this
+bad code example
+\`\`\`
+
+**Why it's bad**: Explanation of the issue.
+
+**Instead**:
+\`\`\`
+// Do this instead
+good code example
+\`\`\`
+```
+
+### Adding a Common Mistake
+
+```markdown
+### Common Mistake: Description
+
+**Symptom**: What goes wrong
+
+**Cause**: Why this happens
+
+**Fix**: How to correct it
+
+**Prevention**: How to avoid it in the future
+```
+
+### Adding a Gotcha
+
+```markdown
+> **Warning**: Brief description of the non-obvious behavior.
+>
+> Details about when this happens and how to handle it.
+```
+
+---
+
+## Interactive Mode
+
+If you're unsure what to update, answer these prompts:
+
+1. **What did you just finish?**
+   - [ ] Fixed a bug
+   - [ ] Implemented a feature
+   - [ ] Refactored code
+   - [ ] Had a discussion about approach
+
+2. **What did you learn or decide?**
+   - Design decision (why X over Y)
+   - Project convention (how we do X)
+   - Non-obvious behavior (gotcha)
+   - Better approach (pattern)
+
+3. **Would future AI/developers need to know this?**
+   - To understand how the code works → Yes, update spec
+   - To maintain or extend the feature → Yes, update spec
+   - To avoid repeating mistakes → Yes, update spec
+   - Purely one-off implementation detail → Maybe skip
+
+4. **Which area does it relate to?**
+   - [ ] Backend code
+   - [ ] Frontend code
+   - [ ] Cross-layer data flow
+   - [ ] Code organization/reuse
+   - [ ] Quality/testing
+
+---
+
+## Quality Checklist
+
+Before finishing your code-spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Did you include executable signatures/contracts?
+- [ ] Did you include validation and error matrix?
+- [ ] Did you include Good/Base/Bad cases?
+- [ ] Did you include required tests with assertion points?
+- [ ] Is it in the right code-spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Learn something → /trellis:update-spec → Knowledge captured
+       ↑                                  ↓
+  /trellis:break-loop ←──────────────────── Future sessions benefit
+  (deep bug analysis)
+```
+
+- `/trellis:break-loop` - Analyzes bugs deeply, often reveals spec updates needed
+- `/trellis:update-spec` - Actually makes the updates
+- `/trellis:finish-work` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.**
+
+The goal is **institutional memory**:
+- What one person learns, everyone benefits from
+- What AI learns in one session, persists to future sessions
+- Mistakes become documented guardrails