modakbul-gongbang/harness/scaffold

/scaffold - Architecture and Harness Scaffolding

Build a foundation that the next feature can extend consistently. The highest-value output is one agreed, working reference flow, not an empty directory tree.

The workflow is L0 Goal -> L1 Environment -> L2 Architecture -> L3 Harness -> L4 Plan -> optional implementation and verification. Planning and verification reports are Markdown. Implementation produces actual source and configuration using the selected project tools; there is no separate scaffold CLI dependency.

Use the user's language. Reuse answers and authorization already provided. The layers are review checkpoints, not mandatory repeated permission questions. Ask only about unresolved choices that materially affect the result. For a small project, combine the proposed architecture, harness, and tasks into one review. A request to plan only must end at the plan; a request to implement may proceed within its established scope.

Before Writing

Confirm the target directory from the request and inspect it before creating output. Read applicable project instructions, manifests, wrappers/lockfiles, existing harness files, and Git status without reading secret values. Do not treat an existing repository as empty merely because it lacks application code.

• New project: create scaffold-spec.md after confirming the goal.

Create a target directory only within the requested scope.

• Existing project: preserve the current stack, code, configuration, and unrelated user changes.

For harness-only work, adapt the existing project without running an initializer or replacing its architecture. For restructuring, first record the current behavior, working verification commands, and explicitly agreed migration scope. If that scope is unclear, ask before planning a replacement.

• Audit-only request: use /check-harness if installed, or perform a read-only assessment.

The sibling skill is optional and must not be assumed to exist.

• Existing spec: read and resume it when it represents the same goal.

For a different goal, use a distinct output path rather than overwriting the previous work.

Keep all required references within this skill folder. Direct skill installation does not install repository-root hooks, agents, permissions, MCP, or LSP.

Output

Accumulate decisions in {project_dir}/scaffold-spec.md:

# Scaffold Spec: {project}
Created: {date}
Goal: {one-line goal}
Status: {planning / ready / implementing / verified / blocked}
 
## L0: Goal
## L1: Environment
## L2: Architecture Decisions
## L3: Harness Setup
## L4: Plan

Use the actual chosen filename when resuming or keeping multiple specs. After implementation, write scaffold-verification.md beside the spec, or a correspondingly distinct report name. Do not produce a completion report merely because a plan was approved.

L0: Goal

Confirm the product purpose, foundation scope, and the smallest complete reference flow. Reflect existing answers instead of asking for confirmation again. Ask about missing consequential requirements before deciding them.

Record:

• Confirmed goal and intended users.
• Reference flow and observable success/failure outcomes.
• Non-goals: product features beyond that flow, production deployment unless explicitly included, and other agreed exclusions.
• Existing-project adaptation or migration boundaries, if applicable.

Do not infer a separate frontend, API server, database, or deployment from a product name alone. For a TODO app, establish persistence and UI needs first. A server-rendered Spring app may fit without a separate Node app. A CLI need not acquire a web server or database.

The reference flow may contain enough business behavior to prove the foundation. Do not exclude all feature behavior and then require an untestable empty exemplar.

L1: Environment

Inspect only tools relevant to the goal and existing project.

Separate observed, required but missing, and not checked. An unavailable required tool becomes a setup task or blocker; it is not permission to change stacks. Record commands and relevant results without secret values.

L2: Architecture Decisions

Resolve Relevant Choices

Consider each dimension, but ask only about unresolved choices affecting the agreed scope. There is no question quota or weighted score to fill. A dimension may be N/A with a reason.

Prioritize questions by consequence: data loss and incompatible consumers matter more than optional formatting preferences. Ask one or two concrete questions at a time, with a recommended option and its material tradeoff. Offer agent-owned decisions when useful. Record delegated decisions as assumed: true, not as user-confirmed facts. Do not invent product policies such as retention, permissions, or payment behavior.

Use these decision states:

• Confirmed: explicitly supplied by the user.
• Project-derived: supported by a file path or existing behavior.
• Delegated: chosen within the user's delegation, with rationale.
• N/A: not applicable, with reason.
• Deferred: excluded optional work, or an unresolved required decision explicitly marked as blocking.

Carry settled choices forward. A deferred optional feature stays outside this scaffold. An unresolved choice needed by the reference flow blocks implementation readiness.

Architecture and Dependency Selection

Use this order: explicit requirements and team constraints, existing project conventions/dependencies, then established framework solutions. Choose the simplest structure that supports the actual behavior. Do not add layers, services, repositories, code generation, or packages just for symmetry.

For a new project, prefer a suitable official initializer or maintained starter over inventing its build setup. For an existing project, adapt its existing build instead of reinitializing it.

Before selecting or adding a dependency:

1. Name the requirement it satisfies and check whether the framework or an existing dependency already provides it.
2. Consult current official documentation or registry metadata for runtime/framework compatibility, maintenance/support, and relevant license constraints.

Use available web or package tooling and record source URLs and the checked date. Do not claim compatibility from memory.

1. Explain the material tradeoff and why an additional package is needed.

Avoid a catalog of alternatives when the team's existing choice already fits.

1. Follow the ecosystem's wrapper, dependency management/BOM, and lockfile conventions.

Resolve dependencies and build during implementation; version selection alone is not proof of compatibility.

If sources cannot be reached, retain established versions where possible and mark new compatibility decisions unverified. A required unverified choice remains an implementation-readiness blocker. Do not replace an established stack with an easier-to-install one.

Prefer reusable framework behavior for logging, configuration, and errors. Add custom shared modules only where there is actual behavior the framework does not supply. Use observable test outcomes and real owned boundaries; fake genuinely external systems only when necessary. Choose API contracts for actual consumer needs, not a universal preference for schema-first or code generation.

Conditional Extensions

Record decisions, evidence, tradeoffs, assumptions, activated extensions, and known gaps. Check the most consequential decision against a concrete failure scenario, such as restart losing required persistent data. Ask a follow-up only if it exposes an unresolved requirement. Present the resulting architecture for review when prior authorization does not already cover the decisions.

L3: Harness Setup

Context and Instructions

Use existing domain terms, business rules, and team conventions. Ask only for missing ones that affect the agreed work. Do not infer unknown business policies from the stack or create generic policy documents to fill a template.

Keep the root CLAUDE.md a concise map:

• Purpose, stack, and meaningful directory boundaries.
• Actual start and verification commands.
• Important project constraints and links with explicit reading conditions.
• Selected project workflows, skills, and hooks when useful.

Example reading conditions:

-Read docs/guides/backend.md before changing Java behavior.
-Read docs/architecture.md before changing module boundaries.

Create only guides that have meaningful content and are needed by the work. Reuse existing guides as the single source instead of duplicating their rules. Length is a maintenance target, not a pass/fail threshold. @import loads with its parent CLAUDE.md; it organizes files without deferring their context cost.

CLAUDE.md and Rules provide model context, not mechanical enforcement. Use an appropriate Hook, permission setting, linter, or CI check for a constraint that needs an executable boundary. Keep shared instructions in the root, directory context in local CLAUDE.md files when useful, and cross-directory file-type guidance in path-scoped Rules. Do not create one file per constraint.

Example .claude/rules/java.md:

---
paths:
  -"src/**/*.java"
---
Read docs/guides/backend.md before changing Java behavior.

Rules without paths load unconditionally. Only reference documents that exist or are included in the implementation plan.

Skills, Hooks, Tools, and Review

Start minimal. Suggest a skill only when its recurring or rare critical purpose is clear, for example a project-specific migration or webhook test procedure. A frontend framework does not by itself require a component-generator skill. Docker does not imply deployment, and a CLI does not imply publication. Do not add release/deploy workflows outside the agreed scope.

Before planning hooks or verification tasks, read references/verification.md. Choose hooks for actual failure modes, not for every installed tool.