component-design-with-tdad · git:20260510.3655852 · 2026-05-10 · sha256 d70b14b058ea5120
component-design-with-tdad git:20260510.3655852A
Immutable. This exact content is served forever at /api/v1/blob/d70b14b058ea5120.
---
name: component-design-with-tdad
description: Use when designing a new plugin component (skill, agent, command, or backing script) for the ai-literacy-superpowers plugin or a sister plugin in this marketplace. Surfaces the design questions that the four-layer TDAD architecture implies — component type, tier targeting, scenario shape, FINDING-vs-scenario judgement, modification-vs-refactor heuristic. Loadable by spec-writer, tdd-agent, or directly during human brainstorming. Not a gate; a methodology guide that names the questions to ask before authoring.
---
# Component design with TDAD
When designing a new plugin component — a skill, an agent, a command,
or a backing script — the four-layer TDAD architecture has implications
for the component's *shape* that are easy to miss if the design is
done before the testing discipline is considered. This skill names
the questions to ask at design time so the component ships
test-friendly rather than acquiring (or never acquiring) its scenario
afterwards.
The skill is loadable by:
- The `spec-writer` agent when authoring a spec that adds a new plugin
component
- The `tdd-agent` when operating in its agent-artefact branch (a
scenario file is the RED-phase deliverable)
- Human brainstorming directly, before any agent dispatch
It is **not a gate**. The forcing functions live in HARNESS.md (the
deterministic CI workflows shipped in v0.36.0). This skill packages
the design intelligence those gates assume.
---
## Before reading this skill
The skill assumes familiarity with:
- The four-layer TDAD architecture — see
[the TDAD docs page](../../../docs/tdad/index.md) and
[`tdad_tests/README.md`](../../../tdad_tests/README.md) for the
full architecture and cost-cadence trade-offs
- The plugin's component conventions — see HARNESS.md Context
(Naming and File structure) and CLAUDE.md
- The orchestrator pipeline — see
[`agents/orchestrator.agent.md`](../../agents/orchestrator.agent.md)
for the spec-first ordering and the agent-artefact-scope detection
step (1c)
## When to invoke
Invoke this skill when:
- A spec you are authoring will add a new file under
`ai-literacy-superpowers/skills/<name>/SKILL.md`,
`ai-literacy-superpowers/agents/<name>.agent.md`, or
`ai-literacy-superpowers/commands/<name>.md`
- A spec will add a new bash script under
`ai-literacy-superpowers/scripts/` or a new helper that the
plugin's components depend on
- You are brainstorming whether something *should be* a skill, an
agent, or a command — and the answer informs how the work is
scoped
- A modification to an existing component changes its behavioural
contract and you need to decide whether the existing scenario(s)
should be updated
Do **not** invoke when:
- The change is to docs, CHANGELOG, marketplace metadata, or other
artefacts outside the canonical component paths
- The change is a non-behavioural refactor of an existing component
- The work is gated by a `chore` exemption that explicitly defers
TDAD-discipline application
---
## The five design questions
### 1. What component type is this?
The plugin has four canonical component types, each with different
authoring conventions and TDAD implications:
| Type | Path | What it is | TDAD applies? |
| --- | --- | --- | --- |
| Skill | `skills/<name>/SKILL.md` | Methodology guidance loaded into context | Yes — Layer 1 (structural) + Layer 2 (trigger) by default; Layer 3 case-by-case |
| Agent | `agents/<name>.agent.md` | Charter, tools, behaviour for a dispatchable agent | Yes — Layer 1 (structural); Layer 3 only when the agent has a clear assertable side-effect |
| Command | `commands/<name>.md` | Slash-command pipeline | Yes per the per-category strategy in [`command-tdad-testing-design.md`](../../../docs/superpowers/specs/2026-05-09-command-tdad-testing-design.md) — procedural, orchestration, or model-mediated each have their own approach |
| Backing script | `scripts/<name>.sh` or `hooks/scripts/<name>.sh` | Bash plumbing — parsers, helpers, hook scripts | Yes — Layer 0 (deterministic plumbing), invoked by `tdad_tests/layer0_deterministic/` |
**Question to surface:** *Could this work be done by an existing
component instead of adding a new one?* The plugin already has 71+
components; the cost of adding one more is non-zero (every component
ships with maintenance overhead). Reuse-or-extend before add-new.
For the design heuristics on each type, see the existing
`plugin-dev` skills (`agent-development`, `skill-development`,
`command-development`, `hook-development`) — they cover the
*shape* of each type. This skill names the *TDAD-aware* layer.
### 2. Which TDAD layers does this component warrant?
The four-layer architecture is a cost gradient:
- **Layer 0 (deterministic plumbing)** — bash scripts and parser
libraries the agents depend on. $0, every PR. Applies to every
shell script in `scripts/` or `hooks/scripts/`.
- **Layer 1 (structural)** — frontmatter well-formed, required
sections present, cross-references resolve. $0, every PR.
**Applies to every plugin component by default.**
- **Layer 2 (trigger)** — does the skill description match the
queries it should fire on? ~$0.03/run, nightly + label-gated.
**Applies to skills only** — agents and commands don't have a
description-vs-query match to verify.
- **Layer 3 (behavioural)** — full SDK invocation against fixtures,
rubric judge. $0.05–$0.20/run, nightly + label-gated.
**Case-by-case** — applies when the component has a clear
assertable side-effect that's worth the API spend.
**Default layer targeting** (in the absence of a per-component
decision):
- Skills: `[structural, trigger]` — Layer 1 always, Layer 2 by
default
- Agents: `[structural]` — Layer 1 always, Layer 3 only when the
agent has a clear assertable side-effect (e.g.,
`harness-discoverer`'s scan output, `spec-writer`'s spec.md)
- Commands: per the per-category strategy in
[`command-tdad-testing-design.md`](../../../docs/superpowers/specs/2026-05-09-command-tdad-testing-design.md)
— procedural commands use Option C-direct test-stage helpers;
orchestration commands inherit from agents; model-mediated
commands defer Layer 3 case-by-case
- Backing scripts: `[deterministic]` (Layer 0) only
**Precedence note:** when an implementation spec contains explicit
per-layer guidance (especially for commands, where
`command-tdad-testing-design.md` Amendment 1 makes Layer 3
case-by-case), the spec's per-component judgement governs. The
defaults above are what the agent emits when the spec is silent.
### 3. What does the scenario's `Then` clause look like?
This is the test-quality question. A scenario whose `## Then` section
is empty or trivially satisfied passes Layer 1 (structural — the
section exists) but provides no substantive coverage. Bad scenarios
are worse than no scenarios because they create the appearance of
coverage.
Ask:
- **What falsifiable assertion does the scenario make?** Each `Then`
bullet should be checkable mechanically (Layer 1: file exists,
frontmatter has key X) or against a rubric (Layer 3: output
contains Y, satisfies pattern Z).
- **What's the smallest fixture that exercises the assertion?**
Layer 3 fixtures live in `tdad_tests/fixtures/` and `tdad_tests/scenarios/<type>/<name>/fixtures/`.
A fixture that's larger than necessary slows the test and
obscures the assertion.
- **Does the Rubric describe the acceptance criterion in plain
prose?** The Rubric is read by humans (during scenario review)
and by Layer 3 LLM judges. Both audiences need to know what
"acceptable" means in ambiguous cases.
If you cannot articulate a falsifiable assertion, the artefact may
be a **finding**, not a scenario — see question 5.
### 4. New file or modification of an existing component?
The HARNESS constraint `New plugin components must ship with a TDAD
scenario` scopes only to *new* file additions matching the canonical
component paths. Modifications are NOT gated by the constraint.
For modifications, the heuristic (per
[`docs/superpowers/specs/2026-05-09-orchestrator-tdad-discipline-design.md`](../../../docs/superpowers/specs/2026-05-09-orchestrator-tdad-discipline-design.md)
§5):
- **Update or replace** the relevant scenario(s) when the spec
changes the component's behavioural contract.
- **Leave existing scenarios unchanged** when the spec is a
non-behavioural refactor.
- This is a judgement call. There is no automated check.
If the modification crosses any of these boundaries, treat it as a
contract change and update the scenario:
- The component's frontmatter `description` field changes
- The component's tool boundary changes (agents only)
- A `Given / When / Then` section in the existing scenario no
longer reflects how the component behaves
- The component gains, removes, or renames a section that other
components reference
**The orchestrator's step 1c surfaces the question for
modifications but does not enforce an answer.** When in doubt,
update the scenario.
### 5. Scenario or finding?
The corpus distinguishes two artefact categories under
`tdad_tests/scenarios/<type>/<name>/`:
- **Scenarios** (descriptive `<aspect>.md` filenames, `tier` in
`{structural, trigger, behavioural}`) — falsifiable assertions
about expected behaviour. Authored by the `tdd-agent` in its
agent-artefact branch.
- **Findings** (`FINDING-<aspect>.md` filenames, `tier: finding`) —
documentary architectural notes. Authored manually by the human
designer when the component surfaces an architectural question
that genuinely cannot be expressed as a falsifiable scenario
today.
A finding **does not satisfy** the HARNESS constraint — it is
documentary, not falsifiable. A new component with only a finding
is not adequately covered.
When the design surfaces a hard question that cannot yet be
falsified, author **both** a scenario (covering what *can* be
asserted) and a finding (capturing what cannot, with rationale).
Findings serve the same purpose as `## Notes` sections in specs:
they preserve the question so future readers see it.
For an example of a finding in production, see
[`tdad_tests/scenarios/commands/harness-init/FINDING-command-tdab-gap.md`](../../../tdad_tests/scenarios/commands/harness-init/FINDING-command-tdab-gap.md).
---
## Output of a TDAD-aware design pass
When this skill is invoked during spec-writing or brainstorming, the
output is a brief **Component design** section that the spec carries
explicitly. The section answers the five questions above:
```markdown
## Component design
- **Type**: skill | agent | command | backing script
- **Justification**: why this type rather than the alternatives
(one sentence)
- **TDAD layers targeted**: [structural, trigger, behavioural,
finding] — explicit list, even if the agent's defaults match
- **Scenario shape**: one sentence describing what the `Then` clause
will assert
- **Modification or new?** new | modification of <component-name>
- **Scenario vs finding**: scenario | scenario + finding | finding-only
(with rationale if not the default scenario-only)
```
The spec-first pipeline then carries this section into the diaboli
review (which can object to the type-justification or the
layer-targeting), the cartograph review (which can surface
alternatives the section did not consider), and the tdd-agent's
agent-artefact branch (which uses the section as the authoring
guide).
The section is short by design — it names the design choices, it
does not re-justify them. The justification lives in the spec's
prose.
---
## What this skill does NOT cover
- **The mechanics of authoring a skill, agent, or command** — see
the `plugin-dev` plugin's `agent-development`,
`skill-development`, `command-development`, and
`hook-development` skills for those.
- **The mechanics of authoring a TDAD scenario** — see
[`tdad_tests/README.md`](../../../tdad_tests/README.md) for the
scenario format, frontmatter fields, and corpus conventions.
- **Test execution** — the skill is design-time guidance; running
tests is the job of the `tdad-tests-fast.yml` CI workflow and
the local `pytest` invocations documented in `tdad_tests/README.md`.
- **Validation of design quality** — that's the `/diaboli`
adversarial review's job. This skill names the questions; the
diaboli judges whether the answers are good.
---
## Where to learn more
- [TDAD docs page](../../../docs/tdad/index.md) — the methodology
end-to-end, including how it integrates with the orchestrator
- [`tdad_tests/README.md`](../../../tdad_tests/README.md) — the
runnable test suite, layer-by-layer status, and scenario format
- [Orchestrator-TDAD-discipline design spec](../../../docs/superpowers/specs/2026-05-09-orchestrator-tdad-discipline-design.md)
— the spec that introduced the orchestrator's step 1c, the
`tdd-agent`'s agent-artefact branch, and the constraints
- [Command-TDAD-testing design spec](../../../docs/superpowers/specs/2026-05-09-command-tdad-testing-design.md)
— the per-category strategy for testing the plugin's commands
- The `plugin-dev` plugin's component-authoring skills (separate
marketplace plugin, listed in the user-invocable skill catalogue
as `plugin-dev:agent-development` etc.) — for the *shape* of
each component type