JK Tools

A repository of AI-assistant skills (in the skills/<category>/ layout consumed by npx skills) plus a setup script for the developer tools that support them.

The skills are the product. ./setup.sh installs MCP servers and developer tooling; it does not install skills.

Skills are distributed via npx skills@latest. The most common one-liner — install everything globally for Claude Code:

npx skills@latest add jakkaj/tools -a claude-code -g

Or install into a single project for GitHub Copilot CLI — drop -g to write to the current repo's local path (./.copilot/skills/) instead of globally:

npx skills@latest add jakkaj/tools -a github-copilot

Without a --skill filter that command opens an interactive picker. To install all skills non-interactively (skip the picker), add -y:

npx skills@latest add jakkaj/tools -a github-copilot -y

Just want the spec-driven flow (the-flow — the whole /the-flow SDD pipeline ships as one skill, sub-skills included)? Scope the install with --skill:

# Project-local for GitHub Copilot CLI — run from the target repo's root
npx skills@latest add jakkaj/tools --skill the-flow -a github-copilot

# Or globally for Claude Code
npx skills@latest add jakkaj/tools --skill the-flow -a claude-code -g

For all install patterns (other CLIs, project-local, single-skill, multi-CLI, universal), see INSTALL.md.

For an annotated catalog of every skill, see README_AGENTS.md.

If you want the developer-tool setup (Rust, code2prompt, FlowSpace, Claude Code CLI, Codex CLI, GitHub Copilot CLI, MCP server configuration):

# Modern (uvx)
uvx --from git+https://github.com/jakkaj/tools jk-tools-setup

# From a local clone
git clone https://github.com/jakkaj/tools.git
cd tools
./setup.sh

./setup.sh is idempotent and safe to re-run. It does not touch your skill installs.

• Installs developer tools: Rust, code2prompt, FlowSpace, just, Claude Code CLI, Codex CLI, GitHub Copilot CLI
• Configures MCP servers across the above CLIs and VS Code
• Adds scripts/ to PATH and creates jk- aliases
• Installs the Claude Code status line

./setup.sh used to fan the legacy v2 command files out into five CLI-specific locations under $HOME. That behaviour is gone — those files are now stale but harmless. See MIGRATION.md for an optional cleanup recipe.

See CLAUDE.md for the contributor-facing dev guide (how to add or edit a skill).

One idea survives every refactor of this repo: the engineering harness IS the product. Development infrastructure — just/make recipes, build and seed scripts, test runners, env setup, plus the agent-facing loop on top (Boot → Backpressure → Observe → Retro → Improve) — is not scaffolding; every plan and code change should leave it better than it found it. Agents are real users: test agents, smoke bots, CI runners, and plan-6 companions are real users of the infrastructure, and their failures and "magic wand" wishes are the most honest feedback the harness gets.

The skills that serve that loop live in the external eng-harness family (AI-Substrate/harness-engineering) — this repo carries none of its own. The SDD pipeline reaches the harness through exactly one door, the /eng-harness-flow router, called at five seams with context (--event session-start | post-spec | pre-implement | phase-end | plan-complete); the router decides what the harness should do, and its child skills are private and never named here. To add the loop:

npx skills@latest add AI-Substrate/harness-engineering -a claude-code -g -y

No harness installed? The flow prints one calm warning, then proceeds with standard testing — nothing gates, nothing blocks.

Ownership (inverted by plan-029): AI-Substrate/harness-engineering owns the harness loop end-to-end — setup/provisioning AND the runtime loop. This repo consumes the router and keeps only docs/harness/schemas/ (its copy of the universal retro shape contract — minih keeps its own) and docs/harness/agents/** (frozen read-only retro history).

If old deployed skill slugs linger after renames (for example the retired local harness-* loop skills), use the read-only reports:

just skills-orphans
just doctor-skills

Review the output before deleting anything; the recipes never auto-delete user-installed skills.

# Install in editable mode
uv venv
source .venv/bin/activate
uv pip install -e .

# Run the CLI
jk-tools-setup --dev-mode .

Important: This describes execution mechanics, not the full picture

The workflow below is deliberately focused on the mechanics of building software: how to move from idea through specification, planning, implementation, and review. It produces traceable artifacts, enforces quality gates, and maintains provenance—but the graph ends at merge. It does not address what happens after code ships: production telemetry, business outcomes, customer impact, or whether the work actually moved the needle. A spec can be perfectly executed through this flow and still deliver zero value if it solved the wrong problem, or if nobody measured whether the hypothesis was validated. The SPACE framework (Forsgren et al.) explicitly warns against collapsing "success" into execution metrics alone—activity is not impact, and throughput is not value.

The bigger picture requires treating every spec as a measurable hypothesis with explicit outcome metrics, guardrails, and a feedback loop that extends into production. It requires companion metrics to prevent local optimization (speed without stability, throughput without maintainability). It requires measuring developer satisfaction and flow state, not just delivery velocity. It requires understanding that in bureaucratic cultures, measurement becomes surveillance and people hide information—so the culture around measurement matters as much as the metrics themselves. Frameworks like ESSP and Accelerate provide the scaffolding for this: leading vs. lagging indicators, the four DORA metrics, the importance of small batches and visible work-in-progress, and the recognition that the "fuzzy front end" (problem identification through specification) is part of the value stream, not separate from it. This workflow is a foundation—but foundations without outcomes are just process theatre.

A spec-driven workflow is, at its core, a disciplined way to separate what/why from how, avoiding "solutioneering" into the wrong outcome. A good flow makes that separation explicit: research and specification first, clarification next, architecture and phased planning after, then implementation with traceability, and finally review gates.

Below is the story told stage-by-stage, referring to the command names only as "an example implementation" of the underlying concept.

Before any work can start, system-level constraints must be established. Not because it's bureaucratic, but because an agent will otherwise "helpfully" fill gaps with invention. The most expensive failure mode is when it confidently reintroduces patterns already rejected, violates architecture boundaries, or rebuilds something the system already has.

So the workflow begins with a constitution: a set of rules of engagement that is always "in the room" for every feature and every plan. In this implementation, the plan-0-v2-constitution utility skill creates the canonical doctrine files—guiding principles, enforceable rules, idioms/patterns, and architecture boundaries—under docs/project-rules/.

The important conceptual move here is not the file creation; it's the synchronization: doctrine must be explicitly enforced "downstream" across planning, tasks, implementation, and review. In this flow, that's stated directly: doctrine must be enforced across Constitution → Rules & Idioms → Plan/Tasks/Implementation.

Being precise about what doctrine actually means in practice is critical. The constitution isn't vague values; it's operational constraints like:

• how quality is proven (tests, manual checks, monitors),
• repeatable tooling and environments,
• coding and review standards,
• architecture guardrails and anti-patterns,
• and change governance (who can change doctrine, what evidence is required).

A subtle but powerful element baked into this design: the constitution needs to be kept fresh and considered re-entrant so it preserves user customizations when updated (using explicit user-content markers). That matters because doctrine is living—teams learn—and a good system doesn't punish learning by overwriting hard-won local context.

Why this chapter matters in SDD: This is where "agent drift" is prevented. These are the invariant constraints that make every later artifact more trustworthy.

The discipline here is resisting the urge to write the spec immediately.

Instead, step 1a brings the raw idea and core requirements and asks the agent to do the work that humans often skip under pressure: understand what already exists, what must be respected, and what the real problem edges look like.

In this implementation, the explore stage (/the-flow 1a explore) is explicitly "research before specification," producing a research dossier (or console output) and using parallelism to cover the landscape.

Conceptually, this stage exists to create a research dossier that turns a vague intention into high-fidelity context:

• how similar parts of the codebase work,
• which dependencies and integration points matter,
• what tests and interfaces already exist,
• what conventions and idioms must not be violated,
• and what documentation already tells (or fails to tell).

This flow also goes further than "read the code": the explore stage can detect where internal research hits a wall and external research is warranted (e.g., best practices, security/compliance expectations, library changes). In the FlowSpace-enabled path, the system checks for tool availability and then launches parallel specialized subagents for comprehensive exploration.

Why this chapter matters in SDD: Because the spec is only as good as its context. Step 1a is where guessing stops and grounding begins. It's also where the two classic failures are prevented:

1. building something that already exists, and
2. writing a spec that ignores real constraints and therefore “looks right” but is unbuildable without surprise scope.

Only after the research dossier exists should the spec be written.

This is the moment where the workflow becomes explicitly technology-free: it forces stating what the user needs and why it matters, before deciding how to implement it. This implementation calls this out directly: create the spec from natural language, focusing on user value (WHAT/WHY) with "no tech choices."

In this system, the specify stage (/the-flow 1b specify) produces the spec document in a feature folder and uses a canonical structure that includes goals, non-goals, acceptance criteria, risks/assumptions, open questions, and placeholders for testing and documentation strategy.

Here's the key story beat: 1a feeds 1b. The spec step explicitly checks for an existing research dossier and external research results, reads them, and incorporates them into the spec (including informing complexity scoring and calling out what was incorporated).

The flow also enforces a crucial "honesty mechanism": unknowns aren't glossed over—they're marked with [NEEDS CLARIFICATION: ...] so ambiguity is visible and can be deliberately resolved later.

Finally, an important move that aligns with the "don't measure with story points/LoC" stance: the spec includes complexity scoring based on a rubric (surface area, integration, data/state, novelty, non-functional needs, testing/rollout), mapped into CS-1 through CS-5.

Why this chapter matters in SDD: The spec is the contract that protects outcomes from implementation bias. If 1b is polluted with "how," the ability to evaluate whether the right thing is being built is lost.

A spec that hasn't been clarified is a trap: it looks complete until it hits implementation reality.

So Chapter 2 does something disciplined: ask a small number of high-impact questions, one at a time, and immediately update the spec with the answers. This implementation is explicit: ask ≤8 questions, prioritize only those "truly needed," and after each answer write into ## Clarifications (dated sessions) and update the relevant spec sections immediately.

The first question is non-negotiable: the workflow mode—Simple or Full—must be decided, because the rest of the workflow changes materially based on complexity.

If Simple mode is chosen (best for CS-1/CS-2), the flow tightens: testing defaults to lightweight, the plan becomes single-phase with inline tasks, and the separate task-expansion stage (/the-flow 5 tasks) is skipped entirely — the plan goes straight to implementation (/the-flow 6 implement). If Full mode is chosen (CS-3+), there's a commitment to multi-phase planning and stronger gates.

Why this chapter matters in SDD: This is where "spec as aspiration" becomes "spec as executable intent." The ambiguity surface area shrinks early, when it's cheap.

Sometimes the work needs to be represented in Jira/Azure DevOps/GitHub Issues. But a good workflow is explicit about a key idea: the issue is not the spec; it's a signpost.

So there's an optional step to generate structured issue text from the spec/plan artifacts for external tracking (the plan-2b-v2-prep-issue utility skill), keeping acceptance criteria, goals, non-goals, and complexity visible without collapsing the whole world into an issue tracker description.

Why this matters: It prevents the common "Jira becomes the spec" failure, while still meeting organizational tracking needs.

Now the story shifts: once the team knows what's being built and has resolved ambiguity, "how" finally enters the room.

In this system, the architect stage (/the-flow 3 architect) explicitly states "never skip—this is the implementation blueprint."

The blueprint isn't just a checklist. It's a structured plan document that includes:

• technical context,
• 15–20+ critical research findings produced by parallel subagents,
• a testing philosophy,
• implementation phases with acceptance criteria per phase,
• cross-cutting concerns,
• complexity tracking,
• progress tracking (task tables),
• and a change footnotes ledger to anchor traceability.

This stage is also where the "constitution" stops being philosophy and becomes governance: the architect step applies gates for clarification completeness, constitution alignment, architecture boundaries, and ADR awareness.

An efficiency pattern baked into this design matters a lot in agentic workflows: if a research dossier already exists, the architect step can reduce redundant exploration and shift to "implementation-specific discovery," rather than re-learning the same facts each time.

Why this chapter matters in SDD: This is where a clarified spec converts into an executable, phased strategy that protects delivery and quality. Without it, "spec-driven" becomes "spec-adjacent."

Sometimes a feature requires decisions that outlive the feature itself (e.g., introducing a new datastore, changing a boundary, adopting a pattern that becomes precedent). In those moments, the flow offers an ADR stage: generate an Architectural Decision Record from the spec and clarifications and cross-link it into the plan so future work inherits constraints rather than rediscovering them.

The ADR tooling is notable because it treats ADRs as a system (scan existing ADRs; map doctrine constraints; extract decision context) and enforces quality signals (alternatives, positive/negative codes, etc.).

Why this chapter matters in SDD: It prevents "local optimum" decisions from being repeated as accidental architecture across time.

Earlier versions of the pipeline had a separate /plan-4-complete-the-plan step that ran post-hoc validators against the plan. That step has been collapsed into the architect stage — the gates now run inline during generation.

The architect stage (/the-flow 3 architect) produces the plan in one of two states:

• Status: READY — all seven gates (Clarify, Constitution, Architecture, ADR, Structure, Testing Alignment, Domain Completeness) passed; Full Mode plans continue to /the-flow 5 tasks, Simple Mode plans continue directly to /the-flow 6 implement.
• Status: DRAFT — UNRESOLVED GAPS — one or more gates failed. The plan is still written (so the user has context to fix), but is annotated inline with ⚠️ GAP: … markers at each violation site, plus a final ## Unresolved Gaps table that names exactly what to fix and where.

Conceptually, this is still the pre-spend gate — plan deficiencies caught before the most expensive activity (implementation) begins. The shift is from "generator → safety net → maybe fix" to "fail-fast generator that emits the plan AND the gap list in one pass."

Why this chapter matters in SDD: The cost curve is real: mistakes found in plan are cheaper than mistakes found in code review, and dramatically cheaper than mistakes found in production. Baking the gates into the generator means the user can never silently consume a broken plan downstream — the DRAFT status header and inline gap markers make defects visible in context.

At this point, the focus stops being "the whole feature" and starts being one phase at a time.

The phase-tasks stage (/the-flow 5 tasks) generates a phase dossier including:

• a 9-column task table (with explicit Validation criteria per task),
• an alignment brief (objectives, non-goals, critical findings, ADR constraints, test plan),
• phase footnote stubs and evidence artifacts,
• and a GO/NO-GO ready check.

Importantly, if it's not Phase 1, the system does a prior phase review via subagents to carry forward lessons, dependencies, and discoveries.

Why this chapter matters in SDD: This is how large work becomes measurable without story points: each phase becomes a coherent unit with explicit validations, evidence, and constraints.

Real work never follows the plan perfectly. When unexpected complexity appears mid-phase, the flow offers a controlled detour: generate a subtask dossier that stays within the phase scope, uses its own task IDs, and updates the parent task and plan registries so traceability remains intact.

Why this chapter matters in SDD: It's the antidote to "scope creep by stealth." Surprises can be absorbed without corrupting the plan's integrity.

Between tasks and implementation, this flow recommends a deliberate pause to build shared understanding.

/didyouknow analyzes the current artifacts from multiple perspectives, presents one insight at a time, and immediately updates the docs as it's discussed—creating a durable record in the artifacts themselves rather than leaving insight trapped in chat history.

Why this matters: This is where teams and agents catch conceptual misalignment before it becomes code churn.

Only now does implementation begin.

The implement stage (/the-flow 6 implement) is explicit: this is where coding happens, and it follows the chosen testing approach (Full TDD, TAD, Lightweight, Manual, or Hybrid). It creates an execution log and captures evidence, commands run, and outputs.

Crucially, it automatically calls the progress updater after each task.

Why this chapter matters in SDD: This is where SDD can go wrong if it isn't instrumented: without evidence, "implementation" becomes un-auditable agent output. This flow explicitly prevents that.

This is one of the most distinctive parts of this design: progress tracking is not "tick a checkbox." It's an atomic synchronization across the plan, the phase dossier, and the footnote ledgers.

The progress stage (/the-flow 6a progress) updates all three locations, validates link integrity and status consistency, and declares the execution incomplete if any location isn't updated.

The system also defines a stable identity scheme ("FlowSpace Node IDs") for linking tasks/logs to concrete code entities (file/class/method/function).

The conceptual payoff is visible in the scenarios this enables: questions like "which tasks modified this file?" or "why was this function added?" can be answered by traversing the bidirectional graph between tasks, logs, footnotes, and files.

Why this chapter matters in SDD: This is how shallow "activity metrics" (LoC, commits) shift to evidence-based traceability, without needing humans to maintain it manually.

Finally, review.

The review stage (/the-flow 7 review) is explicitly comprehensive: it checks bidirectional link integrity (task↔log, task↔footnote, plan↔dossier, parent↔subtask), validates doctrine gates (testing approach, mock usage), and runs quality/safety reviews (correctness, security, performance, observability).

It produces a review report and, when needed, a fix-task artifact, and returns a clear verdict: APPROVE vs REQUEST_CHANGES.

If approved, the work proceeds to merge and either starts the next phase or finishes the feature; if changes are requested, it loops back into implementation and re-runs the gates.

Why this chapter matters in SDD: It prevents "spec-driven" from devolving into "agent-driven." Review gates make quality and doctrine compliance an explicit outcome, not an assumption.

This flow is effectively a conveyor belt of increasingly concrete artifacts, with governance and traceability layered in:

• The constitution defines invariants the system must not violate.
• Research (1a) raises fidelity and prevents reinvention.
• Spec (1b) defines outcomes (WHAT/WHY) and makes unknowns explicit.
• Clarify (2) converts ambiguity into deliberate choices (including workflow mode).
• Architect (3) turns intent into a phased blueprint with explicit gates.
• Validate (4) ensures implementation effort isn't spent on a broken plan.
• Phase tasks (5) create executable slices with validations and briefs.
• Implement (6) generates code plus evidence, not just code.
• Atomic tracking (6a) keeps the whole system auditable and navigable.
• Review (7) enforces doctrine, quality, and traceability before ship.

That's the core story. It's not "a bunch of prompts," it's a mechanism for producing: clarity → plan → evidence → quality gates, with explicit control over ambiguity and drift.

A natural next step would be adding the missing layer: how to measure success of the spec (and each stage) using ideas drawn from SPACE, ESSP, and Accelerate—without falling into the "story points / LoC" trap.

MIT