implement-mainspec

Implements a mainspec end-to-end by auto-detecting mode. Sequential mode (≤3 slices) commits slices in order on the current `feature/<feature>` branch. Parallel mode (>3 slices) uses dependency-aware tiered execution with per-slice worktrees, branches, PRs, and auto-merge into the feature branch. Agent-first — invoked headless by the harness dispatcher with the feature slug as its single argument. No human-in-the-loop, no approval gates.

Quality

78%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Critical

Do not install without reviewing

Fix and improve this skill with Tessl

tessl review fix ./skills/sdd/implement-mainspec/SKILL.md

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with executable commands and a well-validated, clearly sequenced workflow across both modes. It loses points mainly on conciseness from triple-stated content and on progressive disclosure from the long monolithic body, despite well-structured one-level references.

Suggestions

Collapse the redundancy between the Workflow Overview block, the detailed phase sections, and the Guidelines DO/DON'T list into a single authoritative sequence to reduce token cost.

Trim justifications Claude can infer (e.g., why a bare worktree lacks gitignored files) to brief inline notes.

Consider externalizing the long Worktree Management and Parallel Tier Execution detail into a reference file so SKILL.md reads more as an overview with one-level-deep pointers.

Dimension	Reasoning	Score
Conciseness	Operational detail is specific and not padded with concepts Claude already knows, but the same material is restated three times — Workflow Overview, detailed phases, and the Guidelines DO/DON'T section — plus mild justifications like the bootstrap rationale, so it could be tightened.	3 / 5
Actionability	Provides copy-paste-ready bash for worktree creation, `gh pr create`, `gh pr merge --merge`, exact `git` sequences, concrete `compute_tiers.py` invocation, and exact commit-message formats covering the common cases.	5 / 5
Workflow Clarity	Phases 0–5 are clearly sequenced with explicit validation (pre-conditions, resume detection), a bounded signal-fix feedback loop (max_signal_iterations: 3), and failure→exit→dispatcher-retry recovery; the batch/destructive cap-at-3 does not apply because validation is present.	5 / 5
Progressive Disclosure	References (subagent-prompt-template, error-handling, release-strategy) and compute_tiers.py are clearly signaled and verified one level deep with no nested references, but the SKILL.md body itself is a dense ~540-line monolith retaining detail that a more overview-oriented split would externalize.	4 / 5
	Total	17 / 20 Passed

Description

76%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is highly specific and distinctive, clearly conveying what the skill does across its two execution modes. Its main weakness is trigger-term quality: the language is system-internal jargon aimed at a dispatcher rather than natural user phrases.

Suggestions

Add a natural-language trigger clause (e.g., 'Use when implementing a mainspec feature end-to-end') so the 'when' reads as a user-facing trigger rather than only a dispatcher invocation note.

Soften jargon like 'harness dispatcher', 'headless', and 'tiered execution' with at least one plain synonym a user might say (e.g., 'run', 'feature implementation').

Consider mentioning the input artifact name users would reference (e.g., 'specs/<feature>/mainspec.md') to broaden natural keyword coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'commits slices in order', 'dependency-aware tiered execution', 'per-slice worktrees, branches, PRs, and auto-merge' — giving comprehensive coverage of what the skill does.	5 / 5
Completeness	'What' is explicit (implements a mainspec end-to-end in two modes) and 'when' is given via equivalent explicit trigger guidance ('invoked headless by the harness dispatcher with the feature slug as its single argument'), but the trigger is dispatcher-oriented rather than a concrete natural-user trigger phrase, so it is not a 5.	4 / 5
Trigger Term Quality	Relevant domain keywords ('mainspec', 'slice', 'feature') appear, but the phrasing is technical jargon ('harness dispatcher', 'headless', 'tiered execution') with no natural user-facing trigger phrases or synonyms.	3 / 5
Distinctiveness Conflict Risk	Occupies a clear narrow niche (mainspec orchestration with sequential/parallel modes in this harness) with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	17 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (540 lines); consider splitting into references/ and linking	Warning
referenced_paths_exist	Referenced path issues: 4 missing	Warning

	Total	14 / 16 Passed

Repository: tdg-ninja/context-specs-factory-ai
Path: skills/sdd/implement-mainspec/SKILL.md
Commit: 3a7a725

Reviewed: about 19 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.