agentleFS
haqalizhaqaliz/assay/.claude/skills/assay-begin-fast/SKILL.md

assay-begin-fast

Skill0 starsChanged 3 days agoApache-2.0View on GitHub

Use when starting work on an Assay unit of work (a GitHub issue id or an inline brief) and you want the fast path straight to an implementation plan. Triggers on "assay-begin-fast", "abf", "abf bug 12", "abf feat skill-ingest", "begin fast".

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    isolate → gather → dig → PRD → plan → implement (TDD): No proposal/diagram deliverables (use assay-begin / ab when you need those).

    line 12
  2. Distinctive:

    Always work through the agents team: Every phase with independent units of work is dispatched to agents and synthesized.

    line 16
  3. Very specific:

    If id is numeric and gh issue view <id> succeeds → use it as the source.

    line 31
  4. Very specific:

    REQUIRED SUB-SKILL: Use assay-worktrees.

    line 38
  5. Very specific:

    Create from master — Assay's base branch is master.

    line 41
  6. Distinctive:

    Read the saved dump.

    line 53
  7. Distinctive:

    Place the work in the pipeline (A1 ingest, A2 sandbox, A3 agent driver, A4 capture and diff, A5 verdict, A6 bundle, A7 corpus, A8 adapters, …

    line 62
  8. Very specific:

    Run uv run pytest after each task.

    line 91
  9. Very specific:

    Commit per task on <type>/<id>/aliz.

    line 94

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Assay Begin (Fast Track)

Overview

Turn a single unit of work into shipped, test-driven code. The fast track is: isolate → gather → dig → PRD → plan → implement (TDD). No proposal/diagram deliverables (use assay-begin / ab when you need those).

Two non-negotiables:

  • Always work through the agents team. Every phase with independent units of work is dispatched to agents and synthesized.
  • Implementation is always test-first, via superpowers:test-driven-development, executed by the agents team.

Invocation: abf <type> <id> — e.g. abf bug 12, abf feat skill-ingest.

  • type ∈ bug | feat | feature | task | chore (normalize feature → feat).
  • id = a GitHub issue number when one exists, otherwise a short descriptive slug.
  • Owner is aliz.

Task source: GitHub issue, tolerate absence

The repo exists on GitHub but likely has no issues filed yet. Expect the fallback path:

  • If id is numeric and gh issue view <id> succeeds → use it as the source.
  • Otherwise → ask the user for a one-paragraph inline brief.

Pipeline

Phase 0 — Isolate in a worktree

REQUIRED SUB-SKILL: Use assay-worktrees.

  • Branch: <type>/<id>/aliz. Worktree dir: .claude/worktrees/<type>-<id>.
  • Create from master — Assay's base branch is master. Prefer origin/master; fall back to local master if the remote ref isn't fetched.
  • Greenfield: uv sync fails until pyproject.toml exists. If your work is the scaffolding, the failing test comes first.

Phase 1 — Gather context (gh, or inline brief)

Save a raw dump to docs/planning/_card/issue.md in the worktree. If no issue is reachable, write the inline brief under a Brief heading.

Phase 2 — Deep dig

  • Read the saved dump.
  • Map the relevant code paths. Assay is greenfield — today "code paths" means docs/technical/CAPABILITY_ROADMAP.md (A1..A10), docs/technical/ARCHITECTURE.md, and docs/ROADMAP.md. Once the engine exists it lives under src/assay/.
  • Produce a short written understanding note: what's really being asked, affected areas, ambiguities, open questions.
  • Honor CLAUDE.md's constraints: execution (a sandboxed, observed run) decides the verdict, never a static scan or a model's opinion. The floor finding classes cannot be lowered. No real secrets or user data ever reach the sandbox.
  • Place the work in the pipeline (A1 ingest, A2 sandbox, A3 agent driver, A4 capture and diff, A5 verdict, A6 bundle, A7 corpus, A8 adapters, A9 hosted, A10 static pre-filter).

Phase 3 — Requirements interview

REQUIRED SUB-SKILL: prd-interview. Confirm a descriptive kebab-case slug. Output: docs/planning/{slug}/prd.md (+ aspect spec.md if decomposed).

Phase 4 — Generate & self-critique the PRD

REQUIRED SUB-SKILL: prd-generator.

⛔ Review gate — STOP

Present the PRD and its flagged gaps. Wait for explicit approval.

Phase 5 — Implementation plan

REQUIRED SUB-SKILL: tech-plan. One aspect at a time. Output: docs/planning/{slug}/{aspect}/plan_YYYYMMDD.md.

Phase 6 — Implement (TDD, agents team)

REQUIRED SUB-SKILL: superpowers:test-driven-development — strict RED → GREEN → REFACTOR. REQUIRED SUB-SKILL: superpowers:subagent-driven-development — one agent per independent task; parallelize with superpowers:dispatching-parallel-agents.

  • Run uv run pytest after each task; keep the branch green. Sandbox and agent-driver tests run offline with recorded traces — no real sandbox escape attempt and no real model call in CI.
  • Commit per task on <type>/<id>/aliz.

Artifact layout (inside the worktree)

docs/planning/
├── _card/issue.md
├── {slug}/prd.md
└── {slug}/{aspect}/plan_*.md

Agents team (mandatory)

REQUIRED SUB-SKILL: superpowers:dispatching-parallel-agents / superpowers:subagent-driven-development (Phase 6).

Common mistakes

MistakeFix
Working in the primary checkoutCreate the Phase 0 worktree first
Branching from anything but masterAssay's base branch is master; prefer origin/master
Slug = bug-12Use a descriptive slug; the id stays in branch/PR
Treating a missing pyproject.toml as fatalGreenfield — scaffold it, test-first
Skipping the review gatePRD must be approved before tech-plan
A verdict from a static scan or model opinionStop and flag — only the sandboxed, observed run decides
Implementing seriallyExecute through the agents team

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.