thanhtung2693/specgate / app/cli/internal/command/local_plugin_assets/skills/specgate-work-preparation
specgate-work-preparation
VerifiedUse when preparing a request or existing source documents for SpecGate approval, creating quick SpecGate work, publishing an artifact version, or repairing artifact readiness before implementation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.4 KB |
| references/preservation.md | markdown | 936 B |
SKILL.md
View on GitHub---
name: specgate-work-preparation
description: Use when preparing a request or existing source documents for SpecGate approval, creating quick SpecGate work, publishing an artifact version, or repairing artifact readiness before implementation.
---
# Preparing Work
Apply the [SpecGate operating contract](../specgate/SKILL.md#operating-contract).
This phase produces an approved implementation handoff; it never implements
product code.
## 1. Define the contract and route
Read the request, repository instructions, and human-selected sources. Show the
title, description, observable criteria, and non-goals; split independently
accepted work. Bind `@check:<name>` only after the human confirms that check and
show which criteria it enforces and which remain reviewed claims.
When the change touches existing behavior, ask what it must preserve. Read
existing tests; propose ordinary acceptance criteria. Bind `@check` only to
exercised behavior; rerun after implementation. Follow the
[preservation recipe](references/preservation.md) when relevant.
In Local mode, offer pinning only when the human wants reviewed commands stable
across agents or resumes; never make it a default quick-work step. Carry each
candidate binding and command/cwd proof to delivery.
Choose one route with the human:
- **Quick work** for a small change that does not need a governed source snapshot.
- **Artifact-backed work** when an existing spec, design, plan, verification
document, or other source must be versioned and approved.
Do not create a durable record until the human approves the displayed contract.
Completion criterion: the human-approved preview names every slice's contract and route.
## 2A. Create quick work
Create quick work with explicit criteria,
then read the approved contract back:
```bash
specgate work create-quick "$TITLE" --description "$DESCRIPTION" \
--ac "$CONFIRMED_CRITERION_1" --json
specgate work show "$WORK_REF" --json
specgate work context "$WORK_REF" --json
```
Never derive criteria from source structure. Stop if the stored contract differs
from the preview.
Completion criterion: the returned Context Pack reproduces the approved quick
contract exactly. Quick work ends here; switch to `specgate-work-delivery`.
## 2B. Preview and publish an artifact
The originating framework owns source paths, names, lifecycle, and Git policy.
Never relocate, copy, rename, delete, commit, or change ignore rules; edit only with authorization.
Roles are routing labels. Map each human-selected source explicitly; never
detect a framework or manufacture documents. Reuse a path under a second role
when policy requires it.
Local `.specgate/rubrics/*.md` edits require authorization, preview and new publication; judge frozen task content, never working files.
Keep the manifest at `.specgate/work/artifact.json`: unchanged relative `path`,
explicit `role`, and one source. Use `content`, repository `repo_file`,
manifest-relative `source_file`, or external absolute `file_url`.
### Local source inventory
For Local artifacts, propose inventory only for independent slices, deferrals,
or requested source coverage; never infer it or add it to quick work. Preview
each ID, text, unchanged path, slice, and deferral. The human confirms complete
`source_criteria` for exact `@source:<id>` mappings. Keep normal Local backups.
Use the human-selected `feature_key`; `request_type` is `new_feature`,
`change_request`, `bugfix`, or `unknown`:
```json
{
"feature_key": "<human-selected-key>",
"request_type": "new_feature",
"documents": [{
"path": "docs/framework/spec.md",
"role": "spec",
"repo_file": "docs/framework/spec.md"
}]
}
```
Never use `..` traversal or copy sources under `.specgate/work`. Preview without
a server write:
```bash
specgate artifact publish --file .specgate/work/artifact.json --preview --json
```
For an update, set the exact `base_version` and compare with the selected base:
```bash
specgate artifact publish --file .specgate/work/artifact.json \
--preview --compare "$BASE_ARTIFACT_ID" --json
```
Show source mapping, exact policy projection, and added/removed/changed/unchanged paths.
Ask `yes`, `no`, or `unknown` for each omitted impact; use human-selected feature
identity or a named work item.
Completion criterion: each source appears once with unchanged path/role;
source files and Git policy change only with authorization.
Publish only after explicit human confirmation of that preview:
```bash
specgate artifact publish --file .specgate/work/artifact.json --json
```
Completion criterion: publication succeeded and its artifact ID and immutable
version are recorded. On failure, stop before readiness.
## 3. Complete readiness
```bash
specgate gates check "$ARTIFACT_ID" --json --summary
```
When pending task IDs exist, complete every frozen task: list them, judge only
their `skill_content`, and write `.specgate/work/gate-<task-id>.json`:
```json
{
"gate": "<gate_key>",
"gate_digest": "<task gate_digest>",
"input_digest": "<task artifact_digest>",
"state": "pass|warn|fail|needs_human_review|not_applicable",
"summary": "<deciding evidence>",
"evaluator": {"executor": "ide_agent", "name": "<agent name>"}
}
```
```bash
specgate gates tasks list "$ARTIFACT_ID" --json
specgate gates tasks submit-result <task-id> \
--file .specgate/work/gate-<task-id>.json --json
```
`tasks list` includes task content and both digests; do not refetch. Copy
digests exactly. `aggregate=not_run` is unfinished; stale digests need a fresh
task, while readiness errors preserve explicit blockers.
Completion criterion: every pending task has a submitted result for its exact
digests, and the final aggregate plus every remaining gap is recorded.
## 4. Repair without taking ownership
For authorized corrections, publish a new version with the same paths, exact
`base_version`, comparison, confirmed preview, and readiness. Ask about product
ambiguity; report out-of-scope gaps without editing their source.
Completion criterion: readiness is acceptable under the stored policy, or each
remaining gap has an explicit human owner and no unauthorized source edit.
## 5. Obtain the human decision
Show the exact immutable snapshot and readiness evidence:
```bash
specgate artifact show "$ARTIFACT_ID" --json
```
Reuse readiness rows from section 3; render every state and hint verbatim:
```text
SpecGate readiness — <artifact-id> <version> (<aggregate>)
[<state>] <gate> — <hint>
Not yet judged: <count>
```
Never call a `fail`, `warn`, `needs_human_review`, or `not_run` gate acceptable,
or hide its row behind the aggregate.
Stop for the human decision. After the human explicitly approves and authorizes
that exact snapshot, run the normal handoff with every confirmed criterion:
```bash
specgate --yes change approve "$ARTIFACT_ID" \
--title "$TITLE" \
--ac "$CONFIRMED_CRITERION_1" \
--json
specgate work context "$WORK_REF" --json
```
Require the returned work item's `lead_artifact_id` to equal the approved
artifact and its Context Pack to reference the governed sources. A conflicting
existing work contract is a blocker, never a silent relink.
For each authorized slice, include its exact `@source:<id>` token. Run
`specgate artifact coverage "$ARTIFACT_ID" --json`; report unassigned entries
and deferrals without creating work or deciding delivery.
Completion criterion: either the human is reviewing the named immutable
artifact, or the approved work reference and matching Context Pack are recorded;
no implementation file was edited in this phase.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |