# Project Scaffold Skill Intent

Detailed model: see `docs/feedback-layer-model.md`.

## Canonical Purpose

This skill exists to help an AI agent turn a specific repository into a
project-specific autonomous development harness.

The goal is not "generate some docs" and not "self-test the skill in
isolation." The goal is to give the agent an environment where it can:

- understand what the project is trying to build
- see the rules it must not violate
- get fast feedback when it breaks something
- tell the difference between a passing edit and a correct edit
- keep iterating without losing context or maintainability

If a future change improves template coverage but does not improve the
project's feedback loops, constraints, verification, or recovery ability,
that change is not aligned with this skill's purpose.

## What The Harness Must Provide

For each target project, the scaffolded harness should make the following
concrete:

1. Project intent and current scope
2. Architecture and implementation constraints
3. Quality gates the agent can run mechanically
4. Runtime or behavior visibility when something fails
5. Milestone and iteration boundaries
6. Recovery paths when an edit goes wrong
7. Documentation that stays useful during long-running work

The exact artifacts can vary by project. The contract does not.

## Core Principle

Do not hardcode project answers into the skill.

Instead, the skill should:

- discover what is true from the repository
- ask the human only for decisions that cannot be safely inferred
- encode the resulting rules, checks, and operating context back into the repo
- prefer machine-checkable feedback over prose promises

This means prompts, manifests, scripts, checks, and operating docs should act as
the project's working harness, not as generic paperwork.

## Operating Model

The operating model is:

1. Before development, discover what is true in the repo and ask the human only
   for decisions that materially shape the harness or priorities.
2. During development, rely primarily on repo-encoded constraints and
   environment feedback, not repeated human intervention.
3. When the agent fails, the harness should help it see what failed, why it
   failed, and what evidence should guide the next attempt.

Human input is for ambiguity, priorities, and irreversible choices. Routine
iteration should be driven by deterministic checks, runtime evidence, and
project-local rules.

## Success Criteria

The skill is successful when a downstream agent can enter a repo and answer:

- What am I building right now?
- What files or layers am I allowed to change?
- What commands tell me whether I broke something?
- What constraints must my code obey?
- How do I know this milestone is actually done?
- If I get stuck or regress quality, what is the recovery path?

## Non-Goals

This repository is not primarily optimized for:

- maximizing the number of generated files
- enforcing one fixed document bundle on every project
- writing beautiful process prose with weak enforcement
- proving the skill repo can grade itself while target projects remain weakly instrumented

## Drift Check

When making changes to this skill, prefer the option that makes the target
project's autonomous development environment stronger.

Use this document as the tie-breaker when README text, template choices, eval
logic, or sub-skill behavior start drifting toward generic scaffolding instead
of project-specific harness construction.
