new-tool-development

Files (1)

• SKILL.md

SKILL.md (first lines)

# New tool development

## Scope and authority

Use this skill as the lifecycle orchestrator for a new independently invoked tool, CLI, service, or reusable executable subsystem. It owns stage entry, status, approval, invalidation, routing, and implementation readiness—not the substantive contents of the brief, requirements, or specification.

Exclude private build or deployment hooks that only extend an existing workflow without introducing a standalone tool or subsystem.

Keep three logically separate canonical artifacts:

- **Product brief — why and scope:** problem, users, intended outcome, boundaries, and non-goals.
- **Requirements document — observable what:** user-visible behavior, constraints, acceptance conditions, and quality requirements.
- **Implementation specification — how:** design, interfaces, execution details, operational treatment, and verification plan.

Logical separation does not require separate files. Requirements and implementation may occupy named sections in one document or co-located **Requirements** and **Implementation** sections in per-topic files, regardless of tool size. Requirements must state observable contracts directly, without relying on implementation sections to supply missing behavior; implementation sections may reference requirements. Keep canonical ownership, status, approval, and invalidation scope identifiable for each artifact.

Do not duplicate normative content across artifacts. Link to the upstream owner instead. Co-location and compaction do not waive review, approval, invalidation, or separate implementation authority.

Do not begin implementation without both a **ready implementation specification** and a **separate explicit implementation authority**. Approval of one artifact never grants authority to implement.

## Initial triage

1. Confirm the request concerns a new tool/subsystem or a lifecycle decision for one.
2. Record the requested activity explicitly: `brief`, `requirements`, `implementation-spec`, optional `implementation-plan`, or `implementation`.
3. Record known stakeholders, existing artifacts, approved non-goals, dependencies, and unresolved decisions. Distinguish observed facts, assumptions, decisions, and unknowns.
4. If the requested activity is absent or the safe scope cannot be determined, stop and ask for clarification; do not infer an activity.
5. Inspect upstream canonical artifacts and their status before drafting or routing downstream work.

## Status model

Use only the statuses needed by each artifact:

- product brief and requirements: `draft`, `approved`, `blocked`, or `invalidated`;
- implementation specification: `draft`, `ready`, `blocked`, or `invalidated`.

A `draft` means the artifact exists and is pending review or approval. Use `blocked` only when progress cannot continue because a prerequisite, authority, or blocking decision is missing; ordinary pending approval remains `draft`. Use `ready` only when the implementation specification is complete, required reviews passed, and its prerequisites remain valid. A status names its evidence: reviewer or approver, date, packet or decision record, and unresolved questions.

A draft is not approved. A review request is not authority. Approval permits the next stage but does not automatically create or draft it.

When recording a status transition, inspect the full artifact for wording that still describes its former status (for example, “this draft” after approval). Correct editorial wording in agent-editable artifacts; for a human-owned brief, report the mismatch or add a permitted TODO instead. If the correction changes meaning, follow the invalidation and approval rules below before proceeding.

## Stage gates and routing

### Product brief

Briefs **must be written by a human**.
Agents may review briefs, and may add `TODO: <summary of suggested changes>` comments, but they must not author or edit the brief otherwise.

Briefs must be explicitly approved by a human before an agent can draft a requirements document.

Briefs must be reviewed by an agent before they can be approved.
Ask yourself: are the goals of this tool clear? Do you have enough information to draft a requirements document?
What open questions remain?

### Requirements document

Draft only requirements when `requirements` is explicitly requested and the approved brief is current. Route authorship to **`requirements-definition`**. Use **`human-review-packets`** to frame the human approval request. The review packet is a skim packet: a concise summary of scope, observable behaviors, acceptance conditions, constraints, changed assumptions, and unresolved questions, with a link/reference to the canonical requirements artifact.

Require explicit human approval after the skim packet. Do not treat agent review, a comment, or approval of the brief as requirements approval. While approval is pending, keep requirements `draft`; use `blocked` only when review cannot proceed. Without approval, do not start the implementation specification.

### Implementation specification

Draft only the implementation specification when explicitly requested and the approved requirements are current. The specification is mostly agent-owned.

Use these normal contributors:

- **`technical-docs`** for implementation-spec document form, reader tasks, ownership, and prerequisites;
- **`holistic-writing`** for whole-artifact explanation and reader experience after substantial drafting;
- [Change guidelines](../references/change-with-evidence.md#design-choices) for ordinary code, API, and schema choices, and [testing guidance](../references/testing.md) for test strategy;
- **[design review](../review/references/design.md)** to review the completed specification.

Use these conditional contributors only when their trigger holds:

- **`architecture-design`** for consequential subsystem decomposition or architecture boundaries needing separate analysis;
- [Design alternatives](../architecture-design/references/alternatives.md) for an unresolved architectural choice, and [independent deliberation](../architecture-design/references/deliberation.md) only when independent comparison is needed;
- [Boundary-contract questions](../architecture-design/references/boundary-contracts.md) for unresolved or changed contracts, reusing the selected design rather than starting another declaration phase;
- [Complexity justification](../references/complexity-justification.md) when a mechanism's necessity or required variability remains unclear;
- **`dependency-review`** for proposed third-party dependencies.

Escalation has an explicit authority boundary:

- A change to scope, outcome, or a non-goal requires revision of the brief and explicit human reapproval. Block or invalidate the specification until the approved brief is restored.
- A change to observable behavior, defaults, errors, or compatibility requires revision of the requirements and explicit human reapproval. Block or invalidate the specification until the approved requirements are restored.
- High-consequence technical decisions that remain within approved scope, outcomes, non-goals, and requirements may be escalated and resolved within the specification.

Also escalate unresolved security, trust, destructive-boundary, dependency/operational-cost, reusable-framework, or other blocking decisions; record the escalation and decision rather than silently choosing.

A spec becomes `ready` only after required routed work, validation, and resolution of blocking questions. `ready` does not itself authorize implementation.

You may perform experiments or develop prototypes to inform your decisions, but these must be temporary and discarded once the spec is complete.
You may not refer to experiments in the specification.
If crucial evidence depends on an experiment, document it elsewhere in the repo and refer to that documentation.

An implementation specification should be complete enough that an implementor does not need to make any design decisions.
Continue revising your spec until it meets this criterion.
Judge readiness by the specified candidate space, evidence and validation rules, limits, and no-results/error outcomes—not by whether a preimplementation probe finds a feasible alternative or explains every sampled case. A probe's gap blocks readiness only if it exposes a missing design decision or shows the specified approach cannot meet an approved requirement; otherwise record the gap as evidence and leave the search to implementation.

### Implementation plan

Draft an implementation plan only when `implementation-plan` is explicitly requested and the implementation specification is `ready`. Route the plan to **`implementation-plan`**. It is an optional activity, not an artifact stage and not an approval gate; it must not be created speculatively or treated as implementation authority.

### Implementation handoff

Accept implementation only when:

- brief and requirements are approved and current;
- the implementation specification is `ready`;
- no invalidation trigger is outstanding; and
- a separate human or governing process has granted implementation authority.

If any condition fails, stop at handoff and report the exact missing condition. Route substantive implementation to its own procedure; this skill does not prescribe coding, deployment, or operational execution.

## Invalidation and change control

A normative change to an upstream artifact invalidates all downstream artifacts that depend on the changed content. The same applies when a specification draft proposes a change outside its authority boundary: stop and route the required upstream revision and human reapproval before continuing.

Upstream invalidation rules:

- changed brief invalidates requirements and implementation specification;

From jyn514/dotfiles, Unlicense.

More from jyn514/dotfiles