genesis

Files (24)

• SKILL.md
• genesis-architect.agent.md · agents/
• architectural-patterns.md · assets/
• composition-substrate.md · assets/
• design-patterns.md · assets/
• mermaid-conventions.md · assets/
• apm.md · assets/module-system-adapters/
• pattern-tradeoffs.md · assets/
• primitives.md · assets/
• refactor-patterns.md · assets/
• common.md · assets/runtime-affordances/
• claude-code.md · assets/runtime-affordances/per-harness/
• codex.md · assets/runtime-affordances/per-harness/
• copilot.md · assets/runtime-affordances/per-harness/
• cursor.md · assets/runtime-affordances/per-harness/
• opencode.md · assets/runtime-affordances/per-harness/
• gh-aw.md · assets/runtime-affordances/per-trigger-surface/
• portability-rules.md · assets/runtime-affordances/
• 01-readme-iteration.md · examples/
• 02-review-panel-architecture.md · examples/
• 03-release-notes-single-skill.md · examples/
• 04-pr-review-advisory.md · examples/
• 05-pr-review-verdict.md · examples/
• README.md · examples/

SKILL.md (first lines)

# genesis: agentic primitives architecture (design discipline)

[Architect persona](agents/genesis-architect.agent.md)

This skill encodes a disciplined process for designing agentic
primitive modules. Markdown that steers an LLM is code; you do not
write production code without a design. The output of this skill is
DESIGN ARTIFACTS, not finished modules. A separate coding step
emits the natural-language modules from the artifacts.

## When to activate

- Authoring a new skill, persona scoping file, scope-attached rule
  file, or orchestrator workflow.
- Refactoring an existing module that violates SoC, composition,
  or threading rules (e.g. sequential single-loop where fan-out
  fits).
- Cross-cutting redesigns spanning multiple primitive modules.
- Reviews where structure (not domain content) is in question.

## Hard rules

- Diagrams are written before any natural-language module body.
- No harness-specific syntax appears in the persona reasoning or in
  this SKILL.md. Harness syntax lives only in
  `assets/runtime-affordances/per-harness/<harness>.md` and is
  loaded only at step 7.
- A primitive that targets multiple harnesses MUST be designed
  against `assets/runtime-affordances/common.md` first; reaching
  into a per-harness adapter requires a justified declaration per
  `assets/runtime-affordances/portability-rules.md`.
- The handoff packet at step 6 is the only artifact passed forward.
  No tacit context.

## Process

```
   1 intent + scope
        v
   2 component diagram   <-- load assets/mermaid-conventions.md
        v                    load assets/primitives.md
        v                    load assets/design-patterns.md
        v                    load assets/architectural-patterns.md
        v                    load assets/refactor-patterns.md
   3 thread / sequence diagram
        v
 3.5 composition decision  <-- load assets/composition-substrate.md
        v                    (per-box: inline | sibling | external module)
   4 SoC pass against existing modules
        v
   5 classic + PROSE + LLM-physics compliance check
        v
   6 handoff packet (diagrams + interface sketch + declared targets
                     + module composition table + todos)
        v             [PERSIST PACKET to plan store; truth #5]
        v                                      [DESIGN ENDS HERE]
   ----- caller / coder thread takes over -----
   7a portability check
        v                  load runtime-affordances/common.md (always)
   7b draft natural-       load runtime-affordances/per-harness/<x>.md
      language module      ONLY if step 7a flagged a per-harness need
        v                  load module-system-adapters/<tool>.md
        v                  ONLY if step 3.5 declared external modules
        v                  RELOAD plan before each module / spawn
   8 validate against diagrams + lint (PROSE 5-axis, size budget,
     ASCII, coherent unit, portability honored, declared external
     modules wired correctly)
```

### Step 1 - intent + scope

Write one paragraph: the user-facing capability, the trigger
conditions, the boundary (what it does NOT do). Apply Single
Responsibility: if the paragraph contains "and" connecting two
distinct capabilities, split into two designs.

Also draft the dispatch description that will become this module's
frontmatter `description`: name the trigger nouns and verbs, the
boundary, and the intended invocation mode (FORCED | DISCOVERY |
BOTH). This is the function signature the dispatcher LLM matches
against; see the persona's "Skill dispatch" section.

The description follows four rules from the canonical spec for the
MODULE ENTRYPOINT primitive (see `assets/primitives.md` -- the
agentskills.io optimizing-descriptions page is the load-bearing
authority; verify against the live URL):

- IMPERATIVE phrasing. Frame as an instruction to the agent: "Use
  this skill when ..." rather than declarative "This skill does ...".
- USER INTENT over mechanics. Describe what the user is trying to
  achieve, not the skill's internal procedure.
- INDIRECT TRIGGERS named. List contexts where the skill applies
  EVEN IF the user does not name the domain directly. Be pushy.
- LENGTH CAP <= 1024 characters (canonical spec hard limit per
  `assets/primitives.md` MODULE ENTRYPOINT; silent rejection above
  this).

### Step 2 - component diagram (mermaid)

Load:
- `assets/primitives.md`
- `assets/design-patterns.md`
- `assets/architectural-patterns.md`
- `assets/refactor-patterns.md`
- `assets/mermaid-conventions.md`

Emit a `flowchart` showing every primitive module the design uses
and which other modules it depends on (via links). Mark which
modules already exist vs new. Mark each module with one of:
PERSONA, SKILL, RULE, ORCHESTRATOR, ASSET.

### Step 3 - thread / sequence diagram (mermaid)

Emit a `sequenceDiagram` showing:
- Which thread spawns which (subagent fan-out).
- Where parent waits (fan-in / synthesis).
- Any interlock on shared sinks (one-writer rule).

Pattern selection runs in tier order, ALWAYS:

From JinkzEvol/WarpSDLC, Apache-2.0.

More from JinkzEvol/WarpSDLC