# CLI Forge Design

> Design stage for the cli-forge skill family: define or refresh the generated skill's high-level identity, purpose, positioning, and description contract before downstream stages proceed.

- Skill: `bytelandtechnology/cli-forge-design` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add bytelandtechnology/cli-forge-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bytelandtechnology/cli-forge-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: bytelandtechnology (https://skillmd.com/u/bytelandtechnology)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bytelandtechnology/cli-forge-design

---


# cli-forge Design

Use this stage when the workflow needs one authoritative description contract
for a generated Rust CLI Skill before later stages proceed.

## Purpose

Define the skill's high-level identity: what it is, who it serves, and how it
is positioned. Produce a single approved description contract that all
downstream surfaces must reuse instead of inventing competing wording.

This stage answers the question **"What is this skill?"** The detailed CLI
contract (commands, flags, formats) belongs to the Plan stage downstream.

## Canonical References

- [`./instructions/design-contract.md`](./instructions/design-contract.md)
- [`./planning-brief.md`](./planning-brief.md)
- [`./contracts/design-contract.yml.tpl`](./contracts/design-contract.yml.tpl)

## Entry Gate

| #   | Check                                              | Source                  |
| --- | -------------------------------------------------- | ----------------------- |
| 1   | `handoff.yml` exists with `classification: design` | Router                  |
| 2   | Skill scope is at least partially known            | User request or handoff |

## Required Inputs

- Classified workflow intent from the Router
- Current or proposed skill scope
- Any existing description surfaces that must stay aligned
- Whether this is a new skill or a refresh of an existing contract

## Workflow

1. Confirm whether the work creates a new skill or changes the user-facing
   contract of an existing one.
2. Read [`./planning-brief.md`](./planning-brief.md) to load the shared
   constraints.
3. Define or refresh the approved purpose summary (one line).
4. Define or refresh the positioning statement (one paragraph).
5. Record which downstream surfaces must stay synchronized:
   - `Cargo.toml` package.description
   - `SKILL.md` purpose section
   - `README.md` header and description
   - Help text summary line across non-leaf auto-help, `--help`, and
     structured `help`
   - Release notes summary (when publish is in scope)
   - npm package description (when publish is in scope)
6. Record the downstream help contract for later stages:
   - leaf defaults stay structured failures instead of auto-help
   - non-leaf defaults auto-render man-like human-readable help
   - `--help` renders man-like human-readable help
   - `help` returns structured output
   - human-readable help preserves `NAME -> SYNOPSIS -> DESCRIPTION ->
     OPTIONS -> FORMATS -> EXAMPLES -> EXIT CODES`
7. Record the publish contract for later release work: Publish owns both the
   repo-native GitHub Release and npm publication.
8. Generate `.cli-forge/design-contract.yml` using the format defined in
   [`./contracts/design-contract.yml.tpl`](./contracts/design-contract.yml.tpl).
9. Request user approval of the design contract before moving forward. Call the runtime's dialog-based chooser
   (e.g., `AskUserQuestion`) with the options `approve and continue`, `request
   changes`, or `stop for now` when it is available. If no dialog-based chooser
   is available, use a numbered text menu with the same three options and add
   `Other: <custom response>` as the fallback escape hatch. Accept exact replies
   `1`, `2`, or `3`, or `Other: ...`. If a numeric reply includes additional
   text, ask for clarification before proceeding. Do not require the user to
   type the full option label.

## Outputs

- `.cli-forge/design-contract.yml` — approved description contract

## Exit Gate

| #   | Check                                           |
| --- | ----------------------------------------------- |
| 1   | Single-line purpose summary is approved         |
| 2   | Positioning statement is approved               |
| 3   | Sync surfaces list is complete                  |
| 4   | Help contract is recorded                       |
| 5   | Publish contract is recorded                    |
| 6   | `design-contract.yml` is generated and approved |

## Guardrails

- **CRITICAL DIRECTIVE TO THE ASSISTANT**: You MUST STOP execution and ask for the user's explicit approval after generating `design-contract.yml`. Do NOT proceed to the Plan or Scaffold stage autonomously. Call the runtime's dialog-based chooser (e.g., `AskUserQuestion`) for approval when it is available, or use the standardized numbered text fallback with `1. approve and continue`, `2. request changes`, `3. stop for now`, and `Other: <custom response>`.
- This stage is the authoritative source for user-facing purpose and
  positioning. Downstream stages consume the approved contract; they do not
  redefine it.
- Do not define CLI commands, flags, or output formats here. That work belongs
  to the Plan stage.
- When publish support is later adopted, all release-facing wording must reuse
  the approved summary.
- npm package descriptions must reuse the same approved contract whenever the
  Publish stage adopts npm publication.

## Next Step

Continue with [`../cli-forge-plan/SKILL.md`](../cli-forge-plan/SKILL.md) to
define the detailed CLI contract.