| name | project-shape |
| description | Use when analyzing or bootstrapping the five-pillar knowledge architecture of a software project: about/heart-and-soul (doctrine), about/legends-and-lore (RFCs/design contracts), about/lay-and-land (topology), about/craft-and-care (execution-quality standards), and openspec/ (capability specs at root). Use when: starting a new project's knowledge structure, auditing documentation health, onboarding, deciding where knowledge belongs, or mapping system topology. Triggers: "project shape", "bootstrap docs", "where should this go", "what's this project about", "project pillars", "heart and soul", "spec structure", "knowledge architecture", "system map", "topology", "lay of the land", "set up project structure".
|
| metadata | {"owner":"tze","authors":["tze","Claude Fable 5","OpenAI Codex"],"status":"active","last_reviewed":"2026-07-13"} |
Project Shape
A project's shape = the knowledge architecture making it comprehensible to humans and LLMs. Not code — structured understanding of what a project is, why it exists, how it works, where it lives, what must be built, who you must be when you change it.
Visualization: prefer /th-engineering (excalidraw-diagram) + SVG render when supported and the diagram materially aids comprehension. Else fall back to Mermaid or prose. Never block shape work on diagram tooling.
Sample triggers
- "Help me set up the docs structure for this project"
- "What's this project about / where should this idea be documented?"
- "Audit our documentation health — are the pillars coherent?"
- "Map this system's topology"
Not for: one concrete feature request (../project-feature-request/ runs
the funnel); prioritization or "what next" (../project-direction/); scored
repo health audits (../project-review/); README/docs craft quality on a
single doc (/th-engineering documentation — this subskill owns where
knowledge lives, not how well one file reads).
The Five-Pillar Model
Five distinct knowledge layers, each answering a different question:
| Pillar | Folder | Local Skill | Question | Content |
|---|
| Doctrine | about/heart-and-soul/ | heart-and-soul | WHY does this exist? | Vision, principles, non-negotiables, scope boundaries, what it is NOT |
| Design Contracts | about/legends-and-lore/ | legends-and-lore | HOW will it work? | RFCs, design docs, wire contracts, state machines, reviews, trade-offs |
| Capability Specs | openspec/ | spec-and-spine | WHAT exactly must be built? | Normative requirements, WHEN/THEN scenarios, testable acceptance criteria |
| Topology | about/lay-and-land/ | lay-and-land | WHERE does everything live and connect? | Component diagrams, dependency boundaries, data flow, deployment topology, integration maps |
| Engineering Standards | about/craft-and-care/ | craft-and-care | WHO ARE WE WHEN WE BUILD? | Implementation quality bar, testing discipline, review expectations, observability, dependency hygiene, documentation, maintainability |
Four pillars live under about/ (project self-knowledge, poetic names). openspec/ stays at root — a product with its own structure/conventions.
Optional .syzygy canon. A governance-plane repo may instead keep its shape under .syzygy/: doctrine at .syzygy/governance/doctrine/, design contracts at .syzygy/governance/contracts/, engineering standards/policies at .syzygy/governance/policies/, topology at .syzygy/map/; openspec/ is unchanged. shape-scan.sh detects either canon (labeling [SYZYGY-CANON]), warns [DUAL-CANON] if a pillar exists in both, and shape-init.sh refuses to scaffold an about/ mirror of a pillar already living under .syzygy/. Only the doctrine path is fixed by that canon's own doctrine; the other three are detection candidates a project's schema RFCs may refine.
Pillars form a traceability chain — Doctrine principle → RFC decision → Spec requirement → Code → Test. Topology cross-cuts all: where doctrine is embodied, contracts apply, specs are implemented, work lands. craft-and-care is the engineering-character cross-cut: who an engineer must be when changing this repo — explicit, careful, reviewable, observable, maintainable.
Quick Start: Assess Shape
Run the scanner for a health report (which pillars exist, maturity, gaps):
bash <skill-path>/scripts/shape-scan.sh [project-root]
For scanner thresholds and conservative scoring rules, read references/maturity-rubric.md — load when interpreting a scan score or asked what counts as structured/shaped/mature.
If scanning is unavailable, check manually for each pillar:
- Doctrine? —
about/heart-and-soul/, heart-and-soul/, vision.md, MANIFESTO.md, PHILOSOPHY.md, or doctrine-like README.md
- Design contracts? —
about/legends-and-lore/, docs/rfcs/, docs/adrs/, numbered design docs, review rounds
- Specs? —
openspec/, specs/, requirements/, WHEN/THEN files, formal requirement IDs
- Topology? —
about/lay-and-land/, maps/, architecture/, component diagrams, deployment docs, ARCHITECTURE.md
- Engineering standards? —
about/craft-and-care/, engineering-bar.md, testing-and-verification.md, review/verification/observability standards, or quality doctrine scattered in contributor docs
Rate each: absent → nascent (scattered) → structured (dedicated folder, some coverage) → mature (comprehensive, traceable, maintained).
Workflow 1: Bootstrap Shape (new project)
Bootstrapping is consultative, not template-filling. Extract shape from the human's head via structured dialogue, synthesis, adversarial review.
Quality gates:
- Most capable model, max thinking budget when available.
- Keep one bootstrap owner. Use one subagent per substantive, independently
reviewable pillar cluster only when work partitions cleanly; group small
adjacent docs so context and review overhead do not exceed the drafting work.
- Never self-review — independent review subagents when the environment supports them.
- Challenge the user — accept vague answers only to push deeper, never to ship.
Fallback modes (degrade presentation, not rigor):
- Full — highest model, independent review subagents, diagrams via
/th-engineering.
- Lite — single agent + deliberate self-critique + user review when subagents unavailable.
- No-diagram — Mermaid or prose when diagram tooling unavailable.
Process:
- Interview — Socratic extraction across five tracks (identity, boundaries, principles, architecture, contracts). Read
references/consultative-bootstrapping.md for question banks + challenge patterns.
- Synthesize — distill answers into drafts. Use the human's own language.
Make trade-offs explicit. Flag contradictions. Split to a pillar/doc-cluster
worker only when the artifact is substantive and independently reviewable.
- Independent review — fresh context reviews stable pillar/doc clusters;
combine coherence + adversarial lenses unless risk warrants separate agents,
then run cross-pillar review at convergence points. Read
references/review-protocol.md.
- Revise + present — incorporate findings, present for validation. If "not quite right" → return to interview, don't patch.
- Scaffold + install — run
shape-init.sh for structure, populate with reviewed docs, install local skills. Vet generated pillar skills with /th-engineering (skill-standards) before relying on them.
Pillar order (top-down, each grounds the next): heart-and-soul → craft-and-care → legends-and-lore → openspec → lay-and-land. Draft craft-and-care right after doctrine is coherent, before implementation planning — mandatory for all non-trivial work. Topology can start in parallel with design contracts once the architecture interview track is done.
Read references/bootstrapping.md for the phase-by-phase guide, including the local-skill authoring and skill-standards review loop.
Workflow 2: Translate Ideas into Requirements
The shape model funnels ideas into code. Idea → doctrine gate → topology placement → design sketch → WHEN/THEN spec scenarios → tasks. Ideas enter fuzzy, exit precise; each pillar sharpens them; bad ideas die early on doctrine misalignment.
To run this funnel end-to-end for one concrete feature request, use ../project-feature-request/SKILL.md. This section is the model it implements.
When ideas don't fit:
- Contradicts doctrine → reject, or evolve doctrine via
references/doctrine-amendment.md —
drafted by agents, adopted only by the human owner, downstream sweep in the
same session.
- No technical path → park; write exploratory RFC when a path emerges.
- Sound but not specifiable → too vague; break down further.
Workflow 3: Audit and Maintain Shape Health
For an existing project, assess cross-pillar coherence and keep docs current.
Assessment dimensions:
- Coverage — specs trace to RFC sections? RFCs align with doctrine?
- Freshness — specs current with code? RFCs updated after implementation reveals design flaws?
- Gaps — code with no spec? Specs with no doctrine? Design docs that never became specs?
- Orphans — doctrine principles no RFC references; RFC sections no spec covers.
- Execution drift — testing/observability/review/compatibility/documentation/dependency/maintenance standards out of sync with how the project is actually changed?
Maintenance protocol when code diverges from docs:
- Detect — compare implementation against spec requirements, RFC contracts, doctrine.
- Update — generate updated sections; group cohesive small edits and split
only substantive, independently reviewable pillar clusters.
- Review the delta — independent review agents on changed sections only.
- Cross-check — cross-pillar review if changes affect multiple pillars.
- Present — show diff + review summary before committing.
Related: ../project-direction/SKILL.md for full direction analysis with priority-weighted plans; ../project-review/SKILL.md (spec-reconciliation mode) for detailed spec-code divergence; ../project-feature-request/SKILL.md for a single idea through the funnel.
Workflow 4: Generate Project Overview
Synthesize pillars into a visual, layman-friendly about/README.md with embedded Excalidraw SVG diagrams — the public face of the project's shape.
Requirements: ≥2 pillars exist (heart-and-soul + one other); use
/th-design (information-design or accessibility) for the overview's human
reading experience when needed, and /th-engineering (excalidraw-diagram) only
when a diagram materially aids comprehension. Fall back to Mermaid/prose;
independent review when available, else explicit accessibility/adversarial
self-check + user validation.
Process: extract layman-relevant essence per pillar → design 3-5 diagrams arguing the project's story → generate via excalidraw-diagram + render SVG (render-view-fix loop) → write structured markdown (thesis → what it's not → how it works → v1 delivers → principles → navigating docs) → review (accessibility + adversarial subagents) → commit to about/README.md, sources in about/assets/.
Read references/generate-overview.md for diagram specs, document skeleton, review-agent prompts, and writing guidelines.
Reference Index
Diagrams
Rendered visuals for the shape model (each .svg has an editable .excalidraw source). Regeneration specs live in references/diagram-specs.md — load only when regenerating with /th-engineering's excalidraw-diagram:
Pillar Guides
| Pillar | Reference | Read when... |
|---|
| Doctrine | references/pillar-heart-and-soul.md | Bootstrapping vision, writing non-negotiables, scoping v1 |
| Design Contracts | references/pillar-legends-and-lore.md | Structuring RFCs, running reviews, capturing trade-offs |
| Capability Specs | references/pillar-spec-and-spine.md | Writing requirements, WHEN/THEN scenarios, spec lifecycle |
| Topology | references/pillar-lay-and-land.md | Mapping components, boundaries, data flow, deployment |
| Engineering Standards | references/pillar-craft-and-care.md | Defining the implementation quality bar, review standards, verification, observability, maintainability |
Process Guides
Scripts
| Script | Run when... |
|---|
scripts/shape-scan.sh [project-root] | Assessing an existing project's shape — reports which pillars exist, their maturity, and gaps |
scripts/shape-init.sh [project-root] [--skills-only] [--tools=...] | Scaffolding pillar directories and generating correctly-formatted local skills |
scripts/self-test.sh | Verifying the scanner/scaffolder against fixtures after changing SKILL.md, shape-scan.sh, or shape-init.sh |
scripts/eval-fallbacks.sh | Confirming constrained-environment fallback behavior is still documented after changing fallback guidance |
Local Skill Installation
Each pillar gets a local navigation skill in .claude/skills/ (and equivalents) — an index with selection guidance, not a copy of pillar content. It says which file to read for a task, not what the file says. Preferred path generates correctly-formatted skills:
bash <skill-path>/scripts/shape-init.sh [project-root] --skills-only --tools=claude,codex
All five pillars need one: heart-and-soul, legends-and-lore, spec-and-spine, lay-and-land, craft-and-care. For the manual path — per-pillar templates, the mandatory name/description-only frontmatter (scanner rejects extra keys), required progressive-discovery structure — read references/local-skill-templates.md. After writing, validate with scripts/shape-scan.sh + scripts/self-test.sh + scripts/eval-fallbacks.sh and fix every reported issue before committing.
Maintenance Expectations
- Keep metadata, scripts, and references consistent. If the model says "five pillars," adapters and companion files must too.
- Treat
shape-scan.sh as an auditor, not a brochure — prefer conservative assessments.
- Re-run
scripts/self-test.sh after changing SKILL.md, shape-scan.sh, or shape-init.sh.
- Re-run
scripts/eval-fallbacks.sh after changing fallback-mode guidance or references.
- Keep
tests/fixtures/ aligned with real scanner behavior — they are package contract, not throwaway data.
Anti-Patterns
- README-as-doctrine — README describes the project to users; doctrine defines what it believes. Don't conflate.
- Monolith docs — one giant ARCHITECTURE.md mixing vision/design/specs. Split into pillars.
- Specs without doctrine — requirements with no grounding get challenged endlessly. Doctrine ends debates.
- Doctrine without specs — principles that never become testable requirements. Specs make doctrine actionable.
- Stale middle — doctrine and code current, RFCs six months old. Design contracts must evolve.
- Pillar without skill — knowledge exists but agents can't find it. Install local skills.
- Self-reviewed docs — the LLM that wrote the doc reviews it in the same context. Use independent subagents.
- Template-filling — handing templates to the user instead of extracting shape through dialogue. Produces bureaucracy, not doctrine.
