Spec: Skill Activation Boundaries

Context

A one-line pure TypeScript package-filter fix in a React repository activated React Doctor, TDD, and Verify Behavior. React Doctor then compared against an unrelated default branch and scanned thousands of files. Shared skill metadata and commands must select these workflows only at their intended boundaries while preserving deliberate orchestration from Debugging Phase and Implement Spec.

Non-Goals

• Change React Doctor itself or its diagnostic rules.
• Change application runtime behavior in Harness Intelligence.
• Remove deliberate Verify Behavior calls from Debugging Phase or Implement Spec.
• Weaken TDD requirements after TDD, test-first, RED/GREEN, or unresolved behavior-design intent selects that workflow.

Requirements Outcomes

OUT-001: React-specific Doctor activation

React Doctor is selected automatically only for explicit Doctor requests or production changes that overlap React runtime APIs.

OUT-002: Branch-correct changed scans

Every documented React Doctor changed-scope scan supplies an explicit base resolved from the checked-out branch's configured upstream.

OUT-003: Intentional TDD activation

TDD is selected automatically for explicit TDD, test-first, RED/GREEN, or unresolved behavior-design intent, without treating an already-understood mechanical bugfix or regression-test request as sufficient activation intent.

OUT-004: Orchestrated behavior verification

Verify Behavior is not a top-level automatically discovered workflow, while Debugging Phase and Implement Spec retain explicit, valid invocation paths for reproduction and verification respectively.

OUT-005: Distributed shared guidance

The authoritative shared-skill changes are committed and pushed from wearedevpunks/skills main, then synchronized into Harness with the exact source receipt and validated across generated consumers.

Acceptance Criteria

• AC-001: React Doctor metadata names only explicit Doctor requests and production changes overlapping React runtime APIs as automatic triggers.
  • Covers: OUT-001
• AC-002: Every --scope changed command in React Doctor guidance includes --base derived from the checked-out branch's configured upstream, with a clear failure path when no upstream is configured.
  • Covers: OUT-002
• AC-003: TDD metadata activates for explicit TDD, test-first, RED/GREEN, or unresolved behavior-design intent and excludes generic bugfix, regression-test, and feature wording as standalone triggers.
  • Covers: OUT-003
• AC-004: Verify Behavior metadata prevents top-level automatic discovery, and contract checks prove Debugging Phase and Implement Spec still point to its reproduce and verify modes.
  • Covers: OUT-004
• AC-005: Focused shared-skill contract tests fail on pre-fix metadata and command contracts, then pass after the changes.
  • Covers: OUT-001
• AC-006: The Harness sync receipt identifies the pushed shared-skills commit and all touched generated mirrors pass repository validation.
  • Covers: OUT-005

Constraints

• Author reusable skill changes only in /home/stefan/repos/skills while its checked-out branch is exactly main; preserve unrelated dirty files.
• Use Writing for Agents for every skill and agent-facing contract edit.
• Commit and push the shared source before running bun run sync:skills in Harness.
• Keep the #206 Harness branch stacked on the final branch/PR head for issue #205 and set its PR base to that branch.
• Do not use Astra subagents.

Dependency Readiness

Ready: issue #205 established local branch team/stefan/issue-205-effect-backend-structure at 7357f43b686f4866e45925f875e458e8c29ef6f3; final implementation closeout must update #206 onto #205's final published head before opening or updating the PR.

Branch/Base Intent

Parent branch: team/stefan/issue-205-effect-backend-structure. Child branch: team/stefan/issue-206-skill-activation-boundaries. The child was created directly from the parent's then-current tip; ancestry must be re-proven after #205 publishes its final commit.

Accepted Technical Decisions

• Shared-skill source remains authoritative; Harness copies are generated distribution surfaces.
• Activation behavior is controlled through concise skill metadata and explicit caller pointers, with contract tests protecting both discovery and orchestration boundaries.
• Changed-scope commands resolve the current branch's configured upstream rather than assuming a repository-wide default branch.

Accepted Testing Decisions

• Add focused Node contract tests in the shared skills repository for metadata triggers, changed-scan commands, and retained caller routes.
• Validate shared source first, then run Harness skill synchronization and the narrowest affected Harness checks before broader validation.

Verification Seams

The public seam is the installed skill contract: frontmatter discovery metadata, documented React Doctor command examples, and explicit $verify-behavior caller text consumed by Codex.

Decision Log