Skills Playbook — How Work Gets Done in SEA-Forge™

This repository uses a spec-first pipeline: ADR → PRD → SDS → SEA™ → AST → IR → Manifest → Codegen → Determinism.

Core Skills (Spec-First Development)

Skill 0 — Orientation (5 minutes)

1. bash tools/doctor.sh
2. nx show projects
3. nx run workspace:check

Success:

• Doctor prints OK
• Affected codegen runs or reports “No specs changes”

Skill 1 — Add a New Bounded Context

1. python tools/sea_new_context.py inventory
2. Edit:
   • specs/inventory/inventory.adr.md
   • specs/inventory/inventory.prd.md
   • specs/inventory/inventory.sds.yaml
   • specs/inventory/inventory.sea
3. Run:
   • nx run specs-inventory:all

Related: Bounded Context Scaffolder, Create Nx Generator How-To

Skill 2 — Model a Command (CQRS)

• Add a Resource for the command
• Add a Flow with:
  • @cqrs { "kind": "command" }
  • @tx { "transactional": true }
  • optionally @idempotency {...}

Then:

• nx run specs-<ctx>:all

Related: Flow Annotation Linter

Skill 3 — Model a Query

• Flow must include:
  • @cqrs { "kind": "query" }
  • recommend @read_model { "name": "<projection>" }

Related: Knowledge Graph Query Skill

Skill 4 — Model an Event

• Flow must include:
  • @cqrs { "kind": "event" }
  • recommend @outbox { "mode": "required" }

Related: Case Management Skill

Skill 5 — Evolution

Use:

• @replaces and @changes on Resource and Flow

Expected:

• IR/manifest retains both lineage and current shape
• codegen can produce compatibility shims or migration notes (depending on your generator policy)

Extended Skills (AI Agent Capabilities)

Skill 6 — Generate Cognitive Artifacts

Use CADSL to generate knowledge work artifacts (checklists, decision trees, kanban boards, mind maps, timelines).

Triggers:

• Project planning needs visualization
• Decision-making requires structure
• Task coordination needs transparency

Process:

1. Identify artifact type (Checklist, DecisionTree, Kanban, MindMap, Timeline)
2. Generate CADSL YAML definition
3. Semantically anchor to Knowledge Graph concepts
4. Render via Artifact Engine

Related: Cognitive Artifacts Builder Skill, Use Cognitive Artifacts How-To

Skill 7 — Orchestrate Case Management

Manage knowledge work using CMMN primitives (Cases, Stages, Tasks, Sentries, Milestones).

Triggers:

• Flexible workflow needed (not rigid waterfall)
• Outcome clear but path uncertain
• Hybrid human-AI team coordination

Process:

1. Define case with desired outcome
2. Model stages with entry/exit criteria
3. Assign tasks via PM-Agent
4. Track artifact reification (Cognitive → Intellectual → Product → Capital)
5. Achieve milestones

Related: Case Management Skill, Case Management SOP, Case Management Handbook

Skill 8 — Debug with Observability

Use OpenTelemetry traces, metrics, and logs to debug production issues.

Triggers:

• Slow request investigation
• Error root cause analysis
• Performance regression detection

Process:

1. Identify symptom (latency, error, resource spike)
2. Query traces/metrics/logs in OpenObserve
3. Correlate semantic events
4. Locate root cause
5. Validate fix with metrics

Related: Observability Debugging Skill, Debug with OTel How-To, Observability Handbook

Skill 9 — Query Knowledge Graph

Validate ConceptIds, discover relationships, explore ontology using SPARQL.

Triggers:

• Semantic anchoring required
• Concept validation needed
• Relationship discovery

Process:

1. Construct SPARQL query
2. Execute via Knowledge Graph Service
3. Validate results
4. Update artifacts with validated ConceptIds

Related: Knowledge Graph Query Skill, Knowledge Graph SOP, DomainForge Handbook

Skill 10 — Multi-Agent Orchestration

Coordinate multiple specialist agents using Softmax Router pattern.

Triggers:

• Task requires multiple domains
• Parallelizable work
• Weighted contribution synthesis

Process:

1. Analyze context
2. Route to specialists (attention weights)
3. Execute in parallel
4. Aggregate contributions
5. Validate result

Related: Cognitive Architecture SOP, Cognitive Architecture Handbook

Skill 11 — Create and Use Custom Skills

Build new AI agent skills as modular packages.

Triggers:

• Repetitive pattern emerges
• Domain-specific workflow needed
• Capability gap identified

Process:

1. Identify workflow pattern
2. Create SKILL.md with YAML frontmatter
3. Document inputs, process, outputs
4. Add examples and gotchas
5. Test with AI agent

Related: Skill Creator Skill

Skill 12 — Collaborative Document Authoring

Co-author specifications, reports, and documentation with AI assistance.

Triggers:

• Spec drafting (ADR, PRD, SDS)
• Report generation
• Documentation updates

Process:

1. Define scope and outline
2. AI agent drafts initial content
3. Human reviews and refines
4. Iterate until complete
5. Export to final format (Markdown, DOCX, PDF)

Related: Doc Coauthoring Skill, Document Operations Handbook

Skill 13 — Work with Structured Documents (DOCX, XLSX, PDF)

Read, write, and style Word, Excel, and PDF documents.

Triggers:

• Report generation (DOCX)
• Data analysis (XLSX)
• Content extraction (PDF)

Process:

• DOCX: Create reports with styles, tables, headers/footers
• XLSX: Build spreadsheets with formulas, charts, pivot tables
• PDF: Extract text and metadata for indexing

Related: DOCX Skill, XLSX Skill, Document Operations Handbook

Advanced Skills

Skill 14 — Bounded Context Scaffolding

Generate complete bounded context structure with ADR/PRD/SDS/SEA™ templates and Nx registration.

Related: Bounded Context Scaffolder

Skill 15 — Create Nx Generators

Build custom code generators for SEA-Forge™ using Nx generator framework.

Related: Create Nx Generator How-To, Nx Generator Standards

Skill 16 — Data Extraction & Conversion

Extract and convert data across formats (JSON, CSV, HTML, XML) for processing.

Related: Convert Skill

Skill 17 — Fetch Web Content

Retrieve web pages and APIs for research and analysis.

Related: Fetch Skill

Troubleshooting Matrix

“No Runtime Code” Enforcement

If you feel tempted to patch generated code:

1. STOP
2. Model the behavior in SEA™ (or in SDS/SEA™ annotations)
3. Update generator templates / mapping rules instead

Exception: Integration adapters under libs/sea/adapters/** (Semantic Kernel, A2A Protocol) — these wrap third-party SDKs and must implement port interfaces from SDS.

Quick Reference: All Skills

Related Documentation

• AGENTS.md - SEA-only, spec-first workflow rules
• ARCHITECTURE.md - System architecture and five pillars
• System Context Map - All specs index
• Handbooks - Operational guides for all domains
• How-To Guides - Step-by-step procedures
• Playbooks - SOPs for complex workflows