Skip to content

thanhtung2693/specgate / app/cli/internal/command/local_plugin_assets/skills/specgate-work-preparation

specgate-work-preparation

Verified

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. 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 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:

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:

{
  "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:

specgate artifact publish --file .specgate/work/artifact.json --preview --json

For an update, set the exact base_version and compare with the selected base:

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:

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

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:

{
  "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>"}
}
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:

specgate artifact show "$ARTIFACT_ID" --json

Reuse readiness rows from section 3; render every state and hint verbatim:

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:

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.

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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall