Skip to content

notque/vexjoy-agent / skills/process/workflow

workflow

Verified

Structured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.

FileKindSize
SKILL.mdskill md13.2 KB
references/adr-template.mdmarkdown9.4 KB
references/agent-upgrade.mdmarkdown12.5 KB
references/article-evaluation-pipeline.mdmarkdown8.9 KB
references/article-evaluation-pipeline/references/report-template.mdmarkdown2.5 KB
references/article-evaluation-pipeline/references/wabi-sabi-classification.mdmarkdown2.4 KB
references/auto-pipeline.mdmarkdown12.5 KB
references/auto-pipeline/references/pipeline-catalog.jsonconfig15.0 KB
references/auto-pipeline/references/pipeline-catalog.mdmarkdown4.3 KB
references/build_dag.pyscript12.5 KB
references/chain-composer.mdmarkdown20.4 KB
references/chain-composer/references/canonical-chains.mdmarkdown13.9 KB
references/comprehensive-review-workflow.jsscript19.3 KB
references/comprehensive-review.mdmarkdown27.8 KB
references/comprehensive-review/references/output-templates.mdmarkdown10.6 KB
references/comprehensive-review/references/wave-0-per-package.mdmarkdown5.6 KB
references/comprehensive-review/references/wave-1-foundation.mdmarkdown10.4 KB
references/comprehensive-review/references/wave-2-deep-dive.mdmarkdown7.3 KB
references/comprehensive-review/references/wave-3-adversarial.mdmarkdown7.4 KB
references/dag-compatibility-matrix.mdmarkdown13.0 KB
references/dag-composition-patterns.mdmarkdown5.0 KB
references/dag-orchestration-advanced.mdmarkdown6.3 KB
references/dag-orchestration-examples.mdmarkdown11.4 KB
references/dag-skill-patterns.mdmarkdown12.5 KB
references/de-ai-pipeline.jsscript14.6 KB
references/de-ai-pipeline.mdmarkdown6.3 KB
references/discover_skills.pyscript12.1 KB
references/do-perspectives.mdmarkdown11.5 KB
references/doc-pipeline.mdmarkdown9.2 KB
references/domain-research.mdmarkdown32.8 KB
references/domain-research/references/task-type-guide.mdmarkdown11.4 KB
references/explore-pipeline.jsscript18.6 KB
references/explore-pipeline.mdmarkdown15.0 KB
references/fan-out-workflow.jsscript9.7 KB
references/fan-out-workflow.pyscript10.4 KB
references/feedback-loop-construction.mdmarkdown14.3 KB
references/fl-design.mdmarkdown9.6 KB
references/fl-error-handling.mdmarkdown8.5 KB
references/fl-implement.mdmarkdown7.6 KB
references/fl-pipeline.mdmarkdown6.0 KB
references/fl-plan.mdmarkdown11.0 KB
references/fl-release.mdmarkdown3.8 KB
references/fl-shared.mdmarkdown3.6 KB
references/fl-validate.mdmarkdown4.5 KB
references/github-profile-rules.mdmarkdown10.5 KB
references/github-profile-rules/references/rule-categories.mdmarkdown6.5 KB
references/hc-SPEC.mdmarkdown3.3 KB
references/hc-domain-playbooks.mdmarkdown15.4 KB
references/hc-ledger.mdmarkdown3.3 KB
references/hc-profiling-tools.mdmarkdown3.7 KB
references/hill-climb.mdmarkdown9.3 KB
references/hook-development-pipeline.mdmarkdown12.9 KB
references/mcp-pipeline-builder.mdmarkdown16.3 KB
references/mcp-pipeline-builder/references/analysis-checklist.mdmarkdown6.2 KB
references/mcp-pipeline-builder/references/design-rules.mdmarkdown7.1 KB
references/mcp-pipeline-builder/references/evaluation-guide.mdmarkdown7.6 KB
references/mcp-pipeline-builder/references/python-scaffold-template.mdmarkdown9.5 KB
references/mcp-pipeline-builder/references/ts-scaffold-template.mdmarkdown1.6 KB
references/mcp-pipeline-builder/scripts/assemble-scaffold.pyscript6.3 KB
references/mcp-pipeline-builder/scripts/register_mcp.pyscript6.9 KB
references/mcp-pipeline-builder/templates/client-cli.ts.tmplother682 B
references/mcp-pipeline-builder/templates/client-http.ts.tmplother1.4 KB
references/mcp-pipeline-builder/templates/index.ts.tmplother1.1 KB
references/mcp-pipeline-builder/templates/package.json.tmplother477 B
references/mcp-pipeline-builder/templates/readme.md.tmplother1.1 KB
references/mcp-pipeline-builder/templates/tools.ts.tmplother3.0 KB
references/mcp-pipeline-builder/templates/ts-scaffold.tmplother556 B
references/mcp-pipeline-builder/templates/tsconfig.json.tmplother408 B
references/ol-SPEC.mdmarkdown2.4 KB
references/ol-state-file.mdmarkdown2.9 KB
references/pipeline-index.jsonconfig23.9 KB
references/pipeline-orchestrator.mdmarkdown15.3 KB
references/pipeline-orchestrator/orchestration-patterns.mdmarkdown8.1 KB
references/pipeline-orchestrator/preferred-patterns.mdmarkdown4.6 KB
references/pipeline-retro.mdmarkdown19.0 KB
references/pipeline-scaffolder.mdmarkdown22.4 KB
references/pipeline-scaffolder/references/architecture-rules.mdmarkdown18.9 KB
references/pipeline-scaffolder/references/generated-skill-template.mdmarkdown1.9 KB
references/pipeline-scaffolder/references/pipeline-spec-format.mdmarkdown36.8 KB
references/pipeline-scaffolder/references/step-menu.mdmarkdown21.5 KB
references/pipeline-scaffolder/scripts/assemble-skill.pyscript6.3 KB
references/pipeline-scaffolder/templates/phases/decision-planning.md.tmplother1.2 KB
references/pipeline-scaffolder/templates/phases/domain-extension.md.tmplother1.5 KB
references/pipeline-scaffolder/templates/phases/generation.md.tmplother427 B
references/pipeline-scaffolder/templates/phases/git-release.md.tmplother1.1 KB
references/pipeline-scaffolder/templates/phases/interaction.md.tmplother965 B
references/pipeline-scaffolder/templates/phases/learning-retro.md.tmplother1.5 KB
references/pipeline-scaffolder/templates/phases/observation.md.tmplother1.3 KB
references/pipeline-scaffolder/templates/phases/research-gathering.md.tmplother1.2 KB
references/pipeline-scaffolder/templates/phases/review.md.tmplother930 B
references/pipeline-scaffolder/templates/phases/safety-guarding.md.tmplother1.7 KB
references/pipeline-scaffolder/templates/phases/structuring.md.tmplother361 B
references/pipeline-scaffolder/templates/phases/synthesis-reporting.md.tmplother1.9 KB
references/pipeline-scaffolder/templates/phases/validation.md.tmplother1.1 KB
references/pipeline-scaffolder/templates/skill-template.md.tmplother12.0 KB
references/pipeline-test-runner.mdmarkdown16.7 KB
references/pl-ambiguity-triage.mdmarkdown2.7 KB
references/pl-check-dimensions.mdmarkdown7.4 KB
references/pl-check-errors.mdmarkdown824 B
references/pl-check-verdict-format.mdmarkdown3.2 KB
references/pl-check.mdmarkdown6.5 KB
references/pl-context-boundary.mdmarkdown1.6 KB
references/pl-depth-first-interview.mdmarkdown11.6 KB
references/pl-empirical-prototype.mdmarkdown825 B
references/pl-executor-ready-plan-template.mdmarkdown7.7 KB
references/pl-human-source-elicitation.mdmarkdown1.5 KB
references/pl-manage.mdmarkdown5.1 KB
references/pl-pause-confirm-and-errors.mdmarkdown2.1 KB
references/pl-pause-extract-decisions.mdmarkdown3.0 KB
references/pl-pause-gather-steps.mdmarkdown2.3 KB
references/pl-pause-synthesize-fields.mdmarkdown2.3 KB
references/pl-pause-write-templates.mdmarkdown5.3 KB
references/pl-pause.mdmarkdown6.5 KB
references/pl-plan-files.mdmarkdown8.4 KB
references/pl-pre-plan.mdmarkdown11.6 KB
references/pl-resume.mdmarkdown12.3 KB
references/pl-spec.mdmarkdown5.2 KB
references/pr-fix-loop.mdmarkdown10.3 KB
references/pr-fix-loop/references/message-formats.mdmarkdown1.6 KB
references/pr-fix-loop/references/publish.mdmarkdown5.4 KB
references/pr-fix-loop/references/review-checklist.mdmarkdown3.4 KB
references/pr-pipeline/references/pr-templates.mdmarkdown5.4 KB
references/pr-pipeline/references/preflight-checklist.mdmarkdown2.8 KB
references/pr-pipeline/references/retro-adr-phases.mdmarkdown2.7 KB
references/pr-pipeline/references/review-fix-loop.mdmarkdown2.0 KB
references/project-coordinator.mdmarkdown6.5 KB
references/project-coordinator/agent-capability-map.mdmarkdown5.4 KB
references/project-coordinator/communication-protocols.mdmarkdown4.5 KB
references/project-coordinator/coordination-playbook.mdmarkdown3.7 KB
references/project-coordinator/death-loop-prevention.mdmarkdown3.6 KB
references/project-coordinator/error-catalog.mdmarkdown2.7 KB
references/project-coordinator/parallel-execution-patterns.mdmarkdown2.8 KB
references/project-coordinator/preferred-patterns.mdmarkdown5.9 KB
references/project-coordinator/todowrite-integration.mdmarkdown5.6 KB
references/research-pipeline.jsscript15.2 KB
references/skill-creation-pipeline.mdmarkdown17.1 KB
references/system-upgrade.mdmarkdown12.8 KB
references/systematic-debugging.mdmarkdown11.0 KB
references/systematic-refactoring.mdmarkdown11.4 KB
references/toolkit-improvement.jsscript39.0 KB
references/toolkit-improvement.mdmarkdown20.5 KB
references/toolkit-improvement/references/adr-template.mdmarkdown10.5 KB
references/toolkit-improvement/references/agent-roster.mdmarkdown15.8 KB
references/workflow-helpers.jsscript12.1 KB
references/workflow-orchestrator.mdmarkdown20.8 KB
references/workflow-orchestrator/references/plan-template.mdmarkdown1.3 KB
references/workflow-orchestrator/references/task-patterns.mdmarkdown23.3 KB
references/workflow-orchestrator/scripts/assemble-plan.pyscript6.9 KB
references/workflow-orchestrator/scripts/validate.pyscript14.4 KB
references/workflow-orchestrator/templates/plan-template.json.tmplother904 B

references/pipeline-scaffolder/references/architecture-rules.md

View on GitHub
# Pipeline Architecture Rules

These rules are enforced by `pipeline-scaffolder` when generating pipeline components. Every scaffolded skill, skill reference, and hook MUST comply.

Repo agents are retired (plan 009). Domain expertise goes in a skill reference (or a new skill), and dispatched work runs on a fresh `general-purpose` worker told which reference to load. Rules below that name agents apply to the domain reference in the repo, and to an agent file only when the owner asks for a private overlay agent (`agents/INDEX.local.json`).

---

## Rule 1: Single-Purpose Components

**BANNED**: Monolithic agent prompts that handle discovery, execution, and integration in one file.

**REQUIRED**: Each component serves exactly one purpose.

| Component Type | Purpose | NOT Its Purpose |
|---------------|---------|-----------------|
| Hook | Detect environment, inject context | Execute logic, make decisions |
| Domain reference | Hold domain expertise that skills load | Define phases, manage routing |
| Overlay agent (owner-requested only) | Coordinate domain work | Scaffold other agents, manage routing |
| Skill | Define methodology and phases | Implement business logic directly |
| Script | Deterministic mechanical work | Interpret results, make judgments |

**Test**: If you can describe a component's purpose using "and", it's doing too much. Split it.

---

## Rule 2: Domain Reference and Agent Size Limits

A domain reference must pass `python3 scripts/validate-references.py --check-size`; move depth into a subdirectory it loads on demand. The rows below apply to the domain reference, and the YAML row only to an overlay agent.

| Constraint | Limit | Enforcement |
|-----------|-------|-------------|
| Main agent file (overlay) | 10,000 words max | Hard gate — move to references/ |
| YAML description (overlay agent) | 3 example blocks | Required by agent template |
| Hardcoded behaviors | 3-5 items | Excess indicates over-engineering |
| Capabilities list | 4-6 items | More suggests scope creep |
| Pattern coverage | 3+ items | Minimum for quality |
| Error categories | 3+ items | Minimum for robustness |

---

## Rule 3: Hook Design Constraints

All hooks MUST:
- Import from `hooks/lib/hook_utils.py`
- Exit 0 on ALL code paths (non-blocking)
- Target <50ms execution time
- Support `CLAUDE_HOOKS_DEBUG` environment variable
- Use `empty_output()` when no detection occurs
- Use `context_output()` to inject context
- Never call subprocesses unless absolutely necessary
- Never modify files or state (read-only detection)

All hooks MUST NOT:
- Block on network calls
- Import heavy libraries (no numpy, pandas, etc.)
- Write to stdout except via `hook_utils` output methods
- Raise unhandled exceptions (always catch and exit 0)

---

## Rule 4: Skill Phase Gates

Every skill MUST have:
- Numbered phases with clear goals
- A **Gate** statement between phases defining completion criteria
- Explicit inputs and outputs for each phase
- No phase may begin until the previous phase's gate is satisfied

**Template**:
```
### Phase N: NAME

**Goal**: [One sentence]

**Steps**: [Numbered list]

**Gate**: [Completion criteria]. Proceed to Phase N+1.
```

---

## Rule 5: Fan-Out/Fan-In Pattern

Pipelines are **component graphs**, not fixed triples. A pipeline may require multiple domain references, multiple skills, multiple hooks, multiple scripts, and reference documentation for each.

```
Phase 1: DISCOVER (sequential — needs full context)
    ↓
Phase 2: SCAFFOLD (fan-out — group by creator type)
    ├─ skill-creator:             Domain reference A, B, C (1..N)
    ├─ skill-creator:   Skill X, Skill Y (1..M)
    ├─ general-purpose + toolkit/references/hook-development.md: Hook 1, Hook 2 (1..K)
    └─ Direct:                    Script 1, Script 2 (1..J)
    ↓ (fan-in — wait for all)
Phase 3: INTEGRATE (sequential — wire component graph)
    ↓
Phase 4: VERIFY (sequential — validate all components + relationships)
```

**Rules**:
- Fan-out ONLY for genuinely independent work items
- Group by creator type: one sub-agent per type handles all components of that type
- For large pipelines, split further: one sub-agent per complex domain reference
- Each fan-out sub-agent receives the Discovery Report AND full Component Manifest
- Fan-in waits for ALL sub-agents before proceeding
- Maximum 10 parallel sub-agents (system limit)
- Reference docs are generated alongside their parent component (not as separate fan-out tasks)

---

## Rule 6: Routing Integration

Every pipeline MUST be routable via `/do`. This means:

1. Skill has `routing:` metadata in YAML frontmatter with `triggers`, `pairs_with`, `complexity`, `category`
2. Skill has trigger keywords in its description, and its Reference Loading Table names the domain reference
3. `routing-table-updater` is invoked to add entries to:
   - `skills/meta/do/SKILL.md` (main routing tables)
   - `skills/meta/do/references/routing-tables.md` (extended tables)
   - `skills/INDEX.json` (skill registry; `agents/INDEX.local.json` only for an owner-requested overlay agent)

**BANNED**: Creating a pipeline that requires manual routing table edits.

---

## Rule 7: No Dead Code

Every generated component must be:
- Referenced by at least one other component (skill loads domain reference, hook triggers skill)
- Routable via `/do` triggers
- Documented in a `commands/` manifest

**BANNED**: Orphan components that are scaffolded but never wired into the system.

---

## Rule 8: Naming Conventions

| Component | Pattern | Examples |
|-----------|---------|----------|
| Domain reference | `{domain}-domain-knowledge.md` or `{domain}-{function}.md` | `migration-domain-knowledge.md`, `prometheus-grafana.md` |
| Overlay agent (owner-requested only) | `{domain}-{function}-engineer` | `migration-safety-engineer`, `review-pipeline-engineer` |
| Skill | `{pipeline-name}` or `{domain}-{function}` | `pipeline-scaffolder`, `migration-validator` |
| Hook | `{pipeline-name}-detector.py` | `pipeline-context-detector.py`, `migration-detector.py` |
| Command | `{action}-{noun}.md` | `create-pipeline.md`, `run-migration.md` |
| References dir | `references/` under the skill (or under an overlay agent) | `skills/{name}/references/`, `private-agents/{name}/references/` |

---

## Rule 9: Reuse Over Recreation

Before creating any component, check:

1. Does a skill reference covering the same domain already exist?
2. Does a skill with the same methodology already exist?
3. Does a hook detecting the same environment already exist?

If YES to any: **bind the existing component** rather than creating a new one. Document the reuse decision in the Discovery Report.

**Threshold**: If an existing component covers 70%+ of the requirement, extend it rather than duplicating.

---

## Rule 10: ADR Enforcement

Every pipeline — both the Pipeline Creator itself and every pipeline it generates — MUST produce an Architectural Decision Record (ADR).

### Pipeline Creator ADR (Phase 0)
The pipeline orchestrator (`pipeline-orchestrator.md`) creates `adr/pipeline-{name}.md` BEFORE discovery. This ADR is a living document updated at each phase. It serves as the pipeline's single source of truth.

### Generated Pipeline ADR
Every pipeline created by the Pipeline Creator MUST include ADR creation as its own Phase 0. The generated skill's instructions MUST include:

```markdown
### Phase 0: ADR

**Goal**: Create a persistent reference document before work begins.

**Step 1**: Create `adr/{pipeline-name}-{task-id}.md` with:
- Context: Why this task is being executed
- Decision: Which approach was chosen and why
- Constraints: What limits apply
- Test Plan: How success will be verified

**Step 2**: Re-read the ADR before every major decision.

**Gate**: ADR file exists. Proceed to Phase 1.
```

**BANNED**: Pipelines that skip ADR creation. Every pipeline, no matter how simple, produces an ADR. The ADR prevents context drift across phases and provides a grading artifact for retrospectives.

---

## Rule 11: Anti-Rationalization Gate

Before finalizing any scaffolded component, check:

| Rationalization | Required Action |
|-----------------|-----------------|
| "This domain reference needs both X and Y responsibilities" | Split into two references |
| "The hook is too simple to create" | Create it anyway — hooks are the pipeline's eyes |
| "We can skip routing integration for now" | No — unroutable pipelines are dead code |
| "This skill doesn't need phase gates" | Yes it does — gates prevent runaway execution |
| "The template is overkill for this" | Follow it anyway — consistency enables tooling |
| "This pipeline doesn't need an ADR" | Yes it does — ADRs prevent context drift and enable retros |

---

## Rule 12: Parallel Research Phase

**Validated by A/B test** (10 trials, 20 outputs — see `adr/pipeline-creator-ab-test.md`).

Any generated pipeline that includes an information-gathering or research phase MUST dispatch parallel research agents rather than performing sequential searches. The A/B test showed that sequential grep-based research produces a **1.40-point gap in Examples quality** and **0.60-point gap in Completeness** compared to parallel multi-agent research.

### When This Rule Applies

A pipeline needs parallel research when it:
- Gathers context about a target (file, module, system, topic)
- Searches the codebase for usage patterns, callers, or integrations
- Needs to understand both the target AND its ecosystem

### Required Pattern

```
Phase N: RESEARCH (Parallel Multi-Agent)

Step 1: Prepare shared context block from prior phase artifacts
Step 2: Dispatch N parallel research agents (default 4, configurable 2-6)
Step 3: Collect and merge research artifacts after all agents complete

Default agents:
  Agent 1: Code Analysis     — internal architecture, data flow, algorithms
  Agent 2: Usage Patterns    — importers, callers, real-world invocation examples
  Agent 3: Context/Ecosystem — related modules, config, system role, tests
  Agent 4: Output/Examples   — return values, output shapes, concrete examples

Each agent:
  - Receives shared context block from prior phases
  - Saves findings to a separate artifact file (/tmp/research-{aspect}.md)
  - Has a 5-minute timeout
  - Operates independently (no inter-agent dependencies)
```

### Why This Matters

| Approach | Examples Score | Completeness Score | A/B Result |
|----------|--------------|-------------------|------------|
| Sequential grep (B v1.0) | 7.40 avg | 9.20 avg | Lost 10/10 |
| Parallel multi-agent (A) | 8.80 avg | 9.80 avg | Won 10/10 |

The gap is NOT in accuracy or structure (both tied within 0.10). It's entirely in research breadth — which directly feeds example richness and completeness.

### Preferred Pattern: Parallel Research

**BANNED**: Research phases that use sequential `grep` or `search` commands without dispatching parallel agents.

**Why wrong**: Sequential search is narrow by construction — each search informs the next, creating tunnel vision. Parallel agents explore independently, producing broader coverage.

**Exception**: If the pipeline's research phase takes <30 seconds total (e.g., single file lookup), sequential is acceptable. But any research involving "find all usages", "discover ecosystem", or "gather examples" MUST be parallel.

---

## Rule 13: Type Compatibility Must Cover All Canonical Chains

**Evidence**: E2E test 4C (Prometheus) found that `scripts/artifact-utils.py` rejected valid operations chains (`ADR → PROBE → ASSESS → PLAN → EXECUTE`). The observation family only accepted `execution-report` and `safety-record` as inputs, but PROBE after ADR requires `decision-record`. E2E test 4D (RabbitMQ) found MONITOR after PROBE was rejected because observation didn't accept `research-artifact`.

**REQUIRED**: The type compatibility matrix in `scripts/artifact-utils.py` must accept all canonical chain patterns from `references/canonical-chains.md`. When adding new canonical chains, run `validate-chain` against each to verify the type matrix supports it.

**Test**: For each canonical chain template in `canonical-chains.md`, create a test JSON and run `validate-chain`. All must pass.

---

## Rule 14: Layer 2 Fixes Only

**Evidence**: Three-Layer Pattern from A/B testing (`adr/pipeline-creator-ab-test.md`). Layer 1 (artifact fix) teaches the system nothing — the same error recurs next generation. Layer 2 (generator fix) propagates to all future pipelines.

**REQUIRED**: When a generated pipeline has a defect, fix the generator component that produced it (template, rule, step menu, or composition logic) — never the generated artifact directly. Then regenerate to validate the fix.

**BANNED**: Editing generated skill files directly to fix issues. Always trace back to the generation link that introduced the problem.

---

## Rule 15: Cross-Reference Before Create

**Evidence**: Post-mortem of self-improving pipeline generator build. Every specification inconsistency (ASSESS family, REFINE output type, canonical chain disagreements, observation consumes) had the same root cause: an agent created a component from a task summary instead of reading the authoritative source documents.

**REQUIRED**: Every agent creating or modifying a component MUST:

1. **Read the ADR** — the single source of truth for the pipeline being built
2. **Read every document the new component depends on** — not summaries, not descriptions, the actual files
3. **Cross-validate output against source documents** — verify that every type, family, step name, and schema reference matches the authoritative source
4. **Cite sources** — the component's ADR entry must list which documents were read during creation

**BANNED**: Creating a component from a task description or summary alone. Every component must be traceable to the authoritative source documents it references.

**BANNED**: Delegating component creation to an agent with "build X that does Y" instructions. Instead, provide the agent with explicit file paths to read and cross-reference requirements.

**Test**: After creating any component, grep it for step names, schema types, and family names. Every one must appear identically in the authoritative source (step-menu.md for steps, pipeline-spec-format.md for schemas).

---

## Rule 16: Single Source of Truth Chain

**Evidence**: Same post-mortem. Four documents defined step families (step-menu.md, pipeline-spec-format.md, canonical-chains.md, artifact-utils.py). They disagreed on ASSESS, BRAINSTORM, NORMALIZE, EXTRACT, and REFINE because each was written independently without cross-referencing the others.

**REQUIRED**: When the same concept appears in multiple documents, exactly one is the authoritative source. All others derive from it.

| Concept | Authoritative Source | Derived Locations |
|---------|---------------------|-------------------|
| Step definitions (name, family, output, consumes) | `step-menu.md` | `pipeline-spec-format.md` Step Name enum, `artifact-utils.py` STEP_FAMILIES |
| Type compatibility matrix | `step-menu.md` Type Compatibility Matrix | `pipeline-spec-format.md` Step Family table, `artifact-utils.py` TYPE_COMPAT |
| Canonical chain templates | `canonical-chains.md` | `pipeline-spec-format.md` Task Type table |
| Artifact schema definitions | `pipeline-spec-format.md` Output Schema enum | `artifact-utils.py` VALID_SCHEMAS |
| Architecture constraints | `architecture-rules.md` | All generated skills and domain references |
| Operator profiles | `pipeline-spec-format.md` Operator Profile enum | `hooks/operator-context-detector.py` |

**Process for updates**:
1. Update the authoritative source FIRST
2. Propagate to ALL derived locations in the SAME session
3. Run `validate-chain` against all canonical chains to confirm consistency
4. Never update a derived location without updating the authoritative source

**BANNED**: Updating a derived location (e.g., artifact-utils.py TYPE_COMPAT) without simultaneously updating the authoritative source (step-menu.md Type Compatibility Matrix).

---

## Rule 17: Mandatory Read List for Component Creation

**Evidence**: Same post-mortem. Agents that read the source documents produced correct output. Agents that worked from summaries produced inconsistencies.

**REQUIRED**: Before creating any component, the creating agent MUST read these files (not summaries — the actual files):

### For Skills
| File | Why |
|------|-----|
| The pipeline ADR | Single source of truth for this pipeline |
| `step-menu.md` | Authoritative step definitions — verify every step name and family |
| `pipeline-spec-format.md` | Contract for step objects, schema types, validation rules |
| `canonical-chains.md` | Canonical chain templates — verify chain matches template |
| `architecture-rules.md` | Constraints that apply to all generated components |
| Every existing component it references | Prevent drift from existing implementations |

### For Domain References
| File | Why |
|------|-----|
| The pipeline ADR | Context and decisions |
| The owning skill's `SKILL.md` and Reference Loading Table | Where the reference is loaded and which signals load it |
| `architecture-rules.md` | Constraints |
| Every skill that loads it | Verify skill references are accurate |

### For Overlay Agents (owner-requested only)
| File | Why |
|------|-----|
| The pipeline ADR | Context and decisions |
| `skills/meta/toolkit/references/skill-creator/agent-template.md` | Required structure |
| `architecture-rules.md` | Constraints |
| Every skill it pairs with | Verify skill references are accurate |

### For Scripts (validators, utilities)
| File | Why |
|------|-----|
| The pipeline ADR | Context |
| `step-menu.md` | Authoritative type definitions to encode |
| Every document that defines types/schemas the script validates | Ensure validator matches spec |

**BANNED**: "I'll create this from the task description" — every component requires reading the mandatory files above.

**Anti-Rationalization**: "The mandatory read list is overkill for a simple component" → The simple components are where inconsistencies hide. Follow the list regardless of perceived complexity.

---

## Rule 18: ADR Hash Required in Pipeline Specs

Every Pipeline Spec JSON produced by `chain-composer` MUST include:
- `adr_path`: path to the ADR that governs this pipeline (relative to repo root)
- `adr_hash`: sha256 hash of that ADR computed at composition time via `adr-query.py hash`

**Verification**: The `pipeline-scaffolder` Phase 1 gate runs:
```bash
python3 ~/.claude/scripts/adr-query.py verify --adr {spec.adr_path} --hash {spec.adr_hash}
```
If exit 1 (hash mismatch): STOP. The ADR changed after composition. Re-run `chain-composer` with the updated ADR before scaffolding.

**Compliance check**: After creating any component, verify against authoritative sources:
```bash
python3 ~/.claude/scripts/adr-compliance.py check --file {file} \
  --step-menu skills/process/workflow/references/pipeline-scaffolder/references/step-menu.md \
  --spec-format skills/process/workflow/references/pipeline-scaffolder/references/pipeline-spec-format.md
```

BANNED: Pipeline Specs without `adr_path` and `adr_hash` fields when generated via the self-improving pipeline generator.
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall