component-design-with-tdad

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 and 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 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 — 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 — 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 §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.

---

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:

## 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 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 — the methodology end-to-end, including how it integrates with the orchestrator
• tdad_tests/README.md — the runnable test suite, layer-by-layer status, and scenario format
• Orchestrator-TDAD-discipline design spec — the spec that introduced the orchestrator's step 1c, the tdd-agent's agent-artefact branch, and the constraints
• Command-TDAD-testing design spec — 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