build-project-agent-stack

name

build-project-agent-stack

description

Inspect an existing software repository and create, synchronize, or update a project-local Agent Engineering Stack that lets coding agents launch the real app or service, drive representative UI/API/DB behavior, compare observed results with explicit expected states, emit redacted evidence, judge PASS/FAIL/BLOCKED, and keep project knowledge, tests, contracts, fixtures, environment instructions, CI gates, and verification infrastructure aligned as the product changes. Use when the user asks to set up, install, bootstrap, sync, refresh, update, maintain, or detect drift in a project-specific agent stack, verification skill, runtime verification controller, evidence loop, or "verified working = done" workflow.

Build Project Agent Stack

Build a repository-specific closed loop:

analyze → implement → build → run → drive → observe → judge → diagnose → fix → reverify → evidence

Do not treat generated Markdown as completion. Finish only after the stack itself has exercised one representative real feature, or has produced a precise BLOCKED result with evidence and required configuration.

Select the operating mode

Infer the mode from the request and repository state. State the selected mode before editing.

• setup: Create the project Agent Stack when no complete stack exists.
• sync: Perform a read-only drift comparison between current source-of-truth files and living Agent Stack artifacts. Return CLEAN, DRIFT, or BLOCKED. Do not mutate product or stack files.
• update: Detect drift, update only affected Agent Stack artifacts and verification infrastructure, rerun relevant checks, and record a new verified baseline. Return CLEAN, CHANGED, PRODUCT_BUG, or BLOCKED.

Treat “최신 상태 확인”, “sync”, “drift 검사”, and “무엇이 오래됐는지 확인” as sync. Treat “최신화”, “업데이트”, “맞춰줘”, “동기화해서 수정” as update. If the user asks to “sync and update,” run sync first and apply update only to confirmed drift.

Never recreate or duplicate an existing stack merely because setup was named. Detect the existing stack and switch to update unless the user explicitly requests replacement.

Operating contract

• Work in the current repository unless the user names another project root.
• Preserve existing product behavior, tests, agent instructions, and unrelated changes.
• Inspect before choosing commands, tools, paths, ports, accounts, or features.
• Reuse the repository's build, test, automation, debug, seed, and observability tools before adding replacements.
• Record an unverified fact as UNKNOWN; record a missing value or dependency as NEEDS_CONFIG.
• Never infer feature success from build success, process startup, one screenshot, or a mocked path alone.
• Prefer development, test, local, sandbox, or staging targets. Require explicit authorization for production writes, real payments/messages, destructive data changes, or paid external calls.
• Keep the runtime/controller layer usable by multiple coding agents. Put agent-specific prompting around a standard CLI or script rather than burying all logic in prose.

Read supporting references

Read stack-contract.md before creating files. It defines the minimum generated system, state model, feature contract, and evidence schema.

Read platform-strategies.md after identifying the application type. Load only the relevant platform section.

Read sync-and-maintenance.md for sync or update, and before generating maintain-project.

Use scripts/validate_generated_stack.py after creation or update. Use scripts/detect_project_drift.py as the default portable drift scanner when the project does not already provide an equivalent. Use scripts/redact_evidence.py when existing project tooling does not already redact captured logs or JSON.

Phase 1 — Establish boundaries and inspect instructions

1. Resolve the project root and current Git/worktree state.
2. Find and read applicable AGENTS.md, CLAUDE.md, .cursorrules, repository docs, and nested instruction files before editing.
3. Inventory existing uncommitted changes. Do not overwrite or clean them.
4. Identify whether the repository is a monorepo and which runnable surfaces are in scope.
5. Treat verification-infrastructure creation as authorized by this skill invocation. Do not treat unrelated product fixes or external system changes as authorized.

Phase 2 — Perform repository reconnaissance

Ground every claim in source or configuration. Inspect at minimum:

• manifests, lockfiles, build files, workspace definitions, and framework configuration;
• documented and scripted dev, build, lint, typecheck, test, E2E, backend, database, and seed commands;
• CI workflows and container/dev-container configuration;
• routes, screens, API handlers/specifications, CLI entry points, jobs, and persistence layers;
• environment-variable names and example env files without printing secret values;
• fixtures, test accounts, mocks, sandboxes, health checks, debug endpoints, logs, and tracing;
• existing browser/mobile automation, API tests, DB tests, accessibility, screenshot, visual regression, and performance tooling.

Run cheap read-only discovery commands where helpful. Do not install a new framework merely because it is familiar.

Create a short internal decision record with:

• project name, purpose, application type, languages, frameworks, package/build system, and monorepo layout;
• verified commands and their source files;
• existing verification capabilities;
• unknowns and configuration gaps;
• selected runtime verification strategy and why it is the smallest adequate choice.

Phase 3 — Choose the project-local layout

Prefer an existing official project convention. If none exists, use .agent/.

Keep these logical parts even when physical paths differ:

1. project-specific verification skill;
2. executable controller or thin command wrapper;
3. machine-readable configuration;
4. feature map and per-feature expected-state documents;
5. maintain-verification skill;
6. maintain-project skill;
7. drift watch configuration and verified sync baseline;
8. ignored evidence workspace;
9. redaction and destructive-action safeguards.

Name the main skill verify-<normalized-project-name> unless repository conventions require another name. Keep maintain-verification separate because it has a narrower mutation boundary. Add maintain-project as the broader source/knowledge/verification/environment drift manager.

Do not copy a generic controller into the repository unchanged. Bind it to commands, ports, routes, selectors, API contracts, devices, and state stores confirmed in this repository.

Phase 4 — Implement the verification controller

Expose small, composable operations appropriate to the project. Aim for:

doctor
launch
stop
status
snapshot
screenshot
console
network
logs
feature <name>
verify <name>
cleanup

For backend, CLI, library, or mobile projects, replace irrelevant commands with platform-native equivalents. Do not force a UI layer onto a non-UI project.

Controller rules:

• support machine-readable JSON for status and verdict-producing commands;
• return nonzero exit codes for failures and distinguish FAIL from BLOCKED;
• make launch/status/cleanup idempotent where practical;
• explain errors with expected state, actual state, and a concrete recovery action;
• add --dry-run, test/sandbox gating, or explicit confirmation around risky operations;
• never echo secrets or persist raw authentication material;
• keep generated runtime artifacts out of source control unless the repository explicitly versions fixtures.

Wrap existing commands and automation rather than duplicating them. A thin dispatcher is enough when the repository already has a strong test harness.

Phase 5 — Build the feature map

Derive features from real routes, UI, APIs, commands, tests, and product documentation. Do not invent roadmap features.

Create an index and one document per representative feature. Each feature document must define:

• purpose and user-facing entry point;
• sub-features in scope;
• exact drive procedure or controller command;
• objective expected state;
• evidence to capture;
• API/DB/external dependencies;
• known gotchas and environment differences;
• runnable verification commands.

Make expected states observable and preferably machine-judgeable. For example, define the required response status, route, rendered state, persisted state, emitted event, and absence of relevant errors instead of merely saying “click Login.”

Prioritize a safe feature that crosses meaningful runtime boundaries for the first dogfood run. Avoid destructive or costly flows.

Phase 6 — Write the three project-local skills

The project verification skill must enforce:

LAUNCH → DOCTOR → DRIVE → OBSERVE → VERIFY → EVIDENCE → CLEANUP

It must teach future agents to:

• select the relevant feature contract;
• run build/static checks and focused tests;
• launch the actual required processes/devices;
• drive the real surface;
• compare every expected check with an observed actual value;
• emit PASS, FAIL, or BLOCKED;
• diagnose and fix product code only when the user's task authorizes product changes;
• cap repeated correction attempts and stop as BLOCKED when the same root cause or external dependency prevents progress.

The maintenance skill must:

• compare current routes/screens/APIs/features with the feature map and controller;
• run representative verification;
• update only verification infrastructure by default;
• report CLEAN, CHANGED, or BLOCKED;
• report product defects with evidence without silently modifying product code.

The maintain-project skill must:

• inspect source, routes/features, tests, API/DB contracts, fixtures/seed/test accounts, dev environment, agent instructions, architecture decisions, and CI/quality gates;
• classify drift by category and cite the changed source-of-truth files;
• run read-only in sync mode and mutate only Agent Stack/living artifacts in update mode;
• call maintain-verification for the verification subset instead of duplicating its logic;
• update only categories actually affected by confirmed drift;
• require relevant tests and runtime verification before recording a new baseline;
• return CLEAN, DRIFT, CHANGED, PRODUCT_BUG, or BLOCKED according to mode.

Phase 7 — Configure drift detection and baselines

Create a project-specific drift watch configuration and verified baseline as defined in sync-and-maintenance.md.

Prefer source-derived artifacts and generators over duplicated prose. Watch only files that carry meaning for this project; do not hash the entire repository or generated/vendor directories.

For the initial baseline:

1. Complete setup and representative dogfood verification.
2. Save the redacted result.
3. Run the drift scanner in record mode using that successful evidence.
4. Keep the watch configuration and baseline in source control unless repository policy says otherwise.

For sync:

1. Run the scanner in check mode.
2. Confirm semantic impact from source rather than blindly treating every file hash as product drift.
3. Report categories, changed files, affected living artifacts, and recommended update commands.
4. Do not write a new baseline.

For update:

1. Run sync.
2. Update only affected Agent Stack artifacts.
3. Run static checks, focused tests, representative runtime verification, and generated-stack validation.
4. Record the new baseline only after successful verification.
5. Preserve prior baseline and evidence when verification fails or is blocked.

Phase 8 — Connect project instructions safely

If the project has an agent instruction file, append or minimally merge a concise verification rule. Preserve all existing instructions.

The rule must state that non-trivial feature work is not complete until relevant build/static checks, focused tests, runtime verification, expected-vs-actual judgment, and evidence are reported. Link to the project-local verification skill/controller using paths that actually exist.

Also require maintain-project sync as a completion check for non-trivial feature, contract, environment, or CI changes. Run maintain-project update when drift is detected.

If no instruction file exists, create one only when consistent with repository conventions; otherwise document the entry point in the stack itself.

Phase 9 — Secure evidence

Store evidence in a timestamped or run-ID directory and ignore ephemeral runs by default. Capture only what proves the checks:

• result JSON;
• focused test output;
• screenshot or semantic snapshot;
• relevant console/network/application logs;
• HTTP response or DB state;
• trace/video only when needed.

Redact passwords, keys, tokens, cookies, authorization headers, private keys, personal data, and unrelated payload bodies before writing evidence. Prefer allowlisting fields over broad raw dumps. Run the bundled redactor only as a fallback; augment it for project-specific secrets.

Phase 10 — Validate and dogfood

1. Run relevant syntax, lint, or unit checks for every added script/controller.

2. Run:

   python3 <this-skill>/scripts/validate_generated_stack.py <project-root> --stack-dir <actual-stack-dir> --require-sync

3. Fix all structural errors. Review warnings rather than suppressing them.

4. Execute the generated stack against at least one representative real feature:

   • launch required services/app/device;
   • run doctor;
   • drive the feature;
   • observe UI/API/DB/log state as applicable;
   • compare expected and actual checks;
   • generate redacted evidence;
   • return PASS, FAIL, or BLOCKED;
   • clean up processes and temporary state.

5. If the first run reveals a stack defect, fix the verification infrastructure and rerun.

6. Do not change product behavior merely to make verification pass. If product fixing was not requested, preserve the failing evidence and report the defect.

7. Change one safe watched fixture or use a temporary copy to prove that sync reports DRIFT, then restore it without touching user changes.

8. Run update against confirmed drift or a disposable fixture and prove that a new baseline cannot be recorded without successful evidence.

Completion gate

Do not claim completion unless:

• repository commands and existing tools were source-verified;
• the three project-local skills, controller, config, feature map, drift watch config, verified sync baseline, and evidence area exist;
• doctor and at least one feature path are callable;
• expected state and machine-readable verdicts exist;
• evidence redaction and risky-operation guards exist;
• the generated-stack validator passes;
• a representative dogfood run has a real verdict;
• sync can distinguish CLEAN, DRIFT, and BLOCKED;
• update changes only affected Agent Stack artifacts and records a baseline only after successful evidence;
• remaining UNKNOWN and NEEDS_CONFIG items are explicit.

Final report

Lead with the dogfood verdict. Then report:

• project name/type/stack;
• reused tests, E2E, CI, debug, and automation;
• exact generated paths;
• verification commands;
• feature-map coverage;
• representative feature, expected state, actual state, and verdict;
• sync/update mode, detected drift categories, changed living artifacts, and baseline result;
• evidence paths;
• remaining configuration;
• risks/limitations;
• recommended next verification target.

Distinguish clearly between verified completion, failure, blocked environment, and unrun scope.