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

74%

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

67%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.

A thorough, highly actionable orchestration playbook with real, correctly-structured bundle files, deterministic preconditions, and strong validation/recovery loops. Its weaknesses are repetitive restatement of mode-applicability and no-approval messaging, a few stale internal references that no longer match the current phase structure, and a couple of abstract steps ('collect results', 'historical code' heuristics) that are not executable as written.

Suggestions

Fix stale cross-references: the References section says to read the subagent prompt template 'when spawning subagents in Phase 4' (spawning is Phase 3) and the release strategy 'when presenting the summary report' (no summary-report phase exists).

Consolidate the repeated 'Applies only to PARALLEL MODE' / 'no approval gates / dispatcher will re-fire' statements into one authoritative statement per concept to reduce token cost without losing clarity.

Make the abstract steps concrete: specify how to collect per-slice success/failure results (e.g., from TaskOutput/agent notification fields), and either inline the conflict-resolution heuristics or point to the file that contains the 'historical code' patterns.

Dimension	Reasoning	Score
Conciseness	The body is dense with operational fact and teaches nothing Claude already knows, but it repeats itself noticeably: 'Applies only to PARALLEL MODE' appears as a standalone line in ~6 sections, the no-approval-gate / dispatcher-re-fire rationale is restated 5+ times, and idempotency is explained in three places. Mostly efficient but could be tightened — not anchor 2, since the padding is redundant emphasis rather than unnecessary concept explanation.	3 / 5
Actionability	Largely copy-paste-ready guidance: concrete bash for worktree creation, PR creation ('gh pr create --head ... --base ...'), auto-merge ('gh pr merge <pr-number> --merge'), and deterministic preconditions, with real referenced files (references/subagent-prompt-template.md, scripts/compute_tiers.py). Minor gaps keep it below anchor 5: 'Collect results: success/failure per slice' is abstract, and 'Same heuristic patterns as the historical code' references heuristics that are neither shown nor accessible.	4 / 5
Workflow Clarity	Clear phased sequence with explicit validation checkpoints (5 deterministic preconditions, resume detection via merge-commit grep, PR state checks, failure exits) and feedback loops (bounded signal-fix loop, dispatcher re-fire retry) — batch merge operations are well-guarded. Minor incoherence prevents anchor 5: headings like 'Phases 2–5', 'Phase 3/5', and the References section pointing to 'spawning subagents in Phase 4' (spawning is Phase 3) blur the phase model.	4 / 5
Progressive Disclosure	Good structure with well-signaled, one-level-deep references that all exist on disk (references/subagent-prompt-template.md, references/error-handling.md, references/release-strategy.md, scripts/compute_tiers.py), and detailed material is appropriately split out of the overview. Below anchor 5 because the References section's trigger conditions are stale ('when presenting the summary report' — no summary-report phase exists in the current workflow).	4 / 5
	Total	15 / 20 Passed

Description

72%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.

A specific, comprehensive, third-person description of a complex orchestration skill with concrete actions and a distinct niche. Its main weaknesses are the absence of natural trigger phrasing ('Use when...') and missing keyword variations, which cap trigger-term quality and completeness below the top anchors.

Suggestions

Add an explicit 'Use when...' clause naming the invocation triggers (e.g., 'Use when the dispatcher needs to implement all slices of a mainspec / when asked to implement a feature spec end-to-end').

Include natural trigger synonyms and artifacts users would mention, such as 'mainspec', 'spec slices', 'slice dependency map', 'implement feature spec', alongside the existing domain jargon.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions — 'commits slices in order on the current feature/<feature> branch', 'dependency-aware tiered execution with per-slice worktrees, branches, PRs, and auto-merge' — covering the full orchestration pipeline with no significant gaps in coverage, matching the top anchor.	5 / 5
Completeness	The 'what' is clear and concrete, and the 'when' is explicitly stated via 'invoked headless by the harness dispatcher with the feature slug as its single argument' — equivalent explicit trigger guidance, so above the weakly-implied anchor 3. It falls short of anchor 5 because there is no direct 'Use when...' phrasing with concrete trigger terms.	4 / 5
Trigger Term Quality	Relevant domain keywords are present ('mainspec', 'slices', 'feature branch', 'dispatcher'), but common variations and natural trigger phrases a user would say are missing. It fits 'some relevant keywords but missing common variations or synonyms' rather than 'good keyword coverage'.	3 / 5
Distinctiveness Conflict Risk	Distinctive vocabulary ('mainspec', 'slice', 'tiered execution', 'feature slug') carves a clear niche with minimal overlap risk, but the opening 'Implements a mainspec end-to-end' could mildly overlap with generic implementation skills — 'mostly distinct; minor overlap risk'.	4 / 5
	Total	16 / 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: 2 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.