feat: add target repo examples and file layout guidance

README.md

@@ -15,8 +15,28 @@ This repo follows a hybrid model:
 
 That avoids baking one project's assumptions into every other project, while still making the maintenance workflow reusable.
 
+## Recommended target-repo layout
+
+When this skill is applied to a real repository, prefer a structure like:
+
+- `AGENTS.md`
+- `ai/project-map.md`
+- `ai/task-templates.md`
+- `ai/risk-guardrails.md`
+- `ai/harness-health.md`
+
+Not every repository needs all files on day one. Start with `AGENTS.md`, then add the rest as the repo grows.
+
+## Examples
+
+- `examples/node-project/`
+- `examples/go-project/`
+- `examples/rust-project/`
+
+These are sample outputs showing what project-local harness artifacts can look like.
+
 ## Suggested next steps
 
-1. Add example target-repo outputs under a separate examples area if you want templates
+1. Add more stack references if your projects use specific frameworks
-2. Add more stack references if your projects use specific frameworks
+2. Optionally create a second skill later for task-template generation only
-3. Optionally create a second skill later for task-template generation only
+3. Add a small script to scaffold target-repo harness files from templates

examples/go-project/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+## Project overview
+This repository is a Go backend service with HTTP endpoints and background jobs.
+
+## Important directories
+- `cmd/server/` — main server entrypoint
+- `internal/api/` — HTTP layer
+- `internal/service/` — business logic
+- `internal/store/` — persistence
+- `internal/jobs/` — background jobs
+- `tests/` — integration tests
+
+## Commands
+- test: `go test ./...`
+- build: `go build ./...`
+- lint: `golangci-lint run`
+
+## Working rules
+- Prefer minimal diffs
+- Avoid touching generated code unless requested
+- Do not change schema or migrations unless requested
+- Identify whether tests need external services before running them
+
+## Additional harness files
+See `ai/project-map.md`, `ai/task-templates.md`, and `ai/risk-guardrails.md`.

examples/go-project/ai/harness-health.md

@@ -0,0 +1,13 @@
+# Harness Health
+
+- project map clarity: partial
+- validation commands: partial
+- fast feedback: weak
+- task templates: partial
+- guardrails: partial
+- doc-code alignment: partial
+
+## Top priorities
+1. Define repo-standard lint and test wrappers
+2. Document service dependencies for integration tests
+3. Clarify package ownership boundaries

examples/go-project/ai/project-map.md

@@ -0,0 +1,10 @@
+# Project Map
+
+## Main structure
+- `cmd/` contains runnable binaries
+- `internal/` contains non-exported app logic
+- `pkg/` is for reusable public packages if present
+
+## Notes
+- Check `Makefile` for repo-preferred command wrappers
+- Some integration tests may depend on Docker or local services

examples/go-project/ai/risk-guardrails.md

@@ -0,0 +1,6 @@
+# Risk Guardrails
+
+- Treat `cmd/` entrypoints and deployment wiring as high risk
+- Do not silently change interfaces consumed by other packages
+- Be careful with goroutines, channels, and context cancellation paths
+- Do not rewrite broad package layouts for a narrow bugfix

examples/go-project/ai/task-templates.md

@@ -0,0 +1,14 @@
+# Task Templates
+
+## Bugfix
+1. Read the affected package and nearby tests
+2. Explain root cause briefly
+3. Implement the smallest fix in the narrowest package possible
+4. Run focused validation, then `go test ./...` if appropriate
+5. Report risks, especially around concurrency and I/O
+
+## Refactor
+1. Preserve public behavior
+2. Avoid package-wide churn unless clearly justified
+3. Keep imports, naming, and package boundaries tidy
+4. Re-run tests after each meaningful step if the refactor is risky

examples/node-project/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+## Project overview
+This repository is a Node.js + TypeScript service for handling billing and subscription events.
+
+## Important directories
+- `src/routes/` — HTTP handlers
+- `src/services/` — business logic
+- `src/db/` — database access
+- `tests/` — unit and integration tests
+- `scripts/` — development and maintenance scripts
+
+## Commands
+- install: `pnpm install`
+- test: `pnpm test`
+- lint: `pnpm lint`
+- typecheck: `pnpm tsc --noEmit`
+- build: `pnpm build`
+
+## Working rules
+- Prefer minimal diffs
+- Do not change database schema unless explicitly requested
+- Do not upgrade dependencies unless explicitly requested
+- Add or update tests for behavior changes
+- Prefer targeted validation first, then broader validation if needed
+
+## Additional harness files
+See `ai/project-map.md`, `ai/task-templates.md`, and `ai/risk-guardrails.md`.

examples/node-project/ai/harness-health.md

@@ -0,0 +1,13 @@
+# Harness Health
+
+- project map clarity: partial
+- validation commands: strong
+- fast feedback: partial
+- task templates: partial
+- guardrails: strong
+- doc-code alignment: partial
+
+## Top priorities
+1. Add a faster unit-test-only command
+2. Document generated-code boundaries more clearly
+3. Keep AGENTS.md aligned with actual routes and services

examples/node-project/ai/project-map.md

@@ -0,0 +1,13 @@
+# Project Map
+
+## Entry points
+- `src/index.ts` — app bootstrap
+- `src/routes/` — route registration
+
+## Main layers
+- routes -> services -> db
+- shared utilities live under `src/lib/`
+
+## Notes
+- Integration tests may require a local database service
+- Some generated types may exist under `src/generated/`; avoid editing them directly unless asked

examples/node-project/ai/risk-guardrails.md

@@ -0,0 +1,7 @@
+# Risk Guardrails
+
+- Do not edit `src/generated/` unless the task is specifically about code generation
+- Do not update lockfiles unless dependency changes are required
+- Do not disable tests to achieve a passing run
+- Treat deployment and CI files as high-risk areas
+- Prefer package- or module-scoped validation before full-suite validation

examples/node-project/ai/task-templates.md

@@ -0,0 +1,20 @@
+# Task Templates
+
+## Bugfix
+Goal: fix a specific bug with minimal API change.
+
+Required flow:
+1. Read relevant implementation and tests
+2. Summarize likely root cause briefly
+3. Implement the smallest safe fix
+4. Run targeted tests, then broader checks if needed
+5. Report changed files and residual risks
+
+## Feature
+Goal: add a small feature without broad refactors.
+
+Required flow:
+1. Inspect related modules and interfaces
+2. Preserve public API unless the task says otherwise
+3. Add tests for new behavior
+4. Run lint, typecheck, and tests

examples/rust-project/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+## Project overview
+This repository is a Rust service or CLI with one or more crates.
+
+## Important directories
+- `src/` — primary crate source
+- `crates/` — workspace member crates if present
+- `tests/` — integration tests
+- `benches/` — benchmarks if present
+
+## Commands
+- test: `cargo test`
+- build: `cargo build`
+- lint: `cargo clippy --all-targets --all-features -- -D warnings`
+- format check: `cargo fmt --check`
+
+## Working rules
+- Prefer minimal diffs
+- Do not casually update `Cargo.lock`
+- Avoid changing workspace structure unless explicitly requested
+- Add or update tests for behavior changes
+
+## Additional harness files
+See `ai/project-map.md`, `ai/task-templates.md`, and `ai/risk-guardrails.md`.

examples/rust-project/ai/harness-health.md

@@ -0,0 +1,13 @@
+# Harness Health
+
+- project map clarity: partial
+- validation commands: strong
+- fast feedback: partial
+- task templates: partial
+- guardrails: strong
+- doc-code alignment: partial
+
+## Top priorities
+1. Document workspace crate roles more clearly
+2. Call out feature-flag-specific validation paths
+3. Keep examples aligned with actual crate boundaries

examples/rust-project/ai/project-map.md

@@ -0,0 +1,10 @@
+# Project Map
+
+## Main structure
+- root crate or workspace declared in `Cargo.toml`
+- `src/main.rs` or `src/lib.rs` as primary entrypoints
+- `crates/` for workspace members where applicable
+
+## Notes
+- Distinguish unit tests from integration tests
+- Check whether feature flags alter build or test behavior

examples/rust-project/ai/risk-guardrails.md

@@ -0,0 +1,6 @@
+# Risk Guardrails
+
+- Do not casually modify `Cargo.lock`
+- Be careful with feature flags and workspace-wide effects
+- Avoid broad lifetime or trait refactors for narrow tasks
+- Treat unsafe code paths as high scrutiny areas

examples/rust-project/ai/task-templates.md

@@ -0,0 +1,14 @@
+# Task Templates
+
+## Bugfix
+1. Read the affected module and relevant tests
+2. Confirm whether the crate is part of a workspace
+3. Implement the narrowest safe fix
+4. Run targeted checks first, then broader cargo validation
+5. Report any feature-flag or cross-crate risks
+
+## Feature
+1. Preserve existing public interfaces unless instructed otherwise
+2. Keep new dependencies to a minimum
+3. Add tests for normal and edge cases
+4. Run fmt, clippy, and tests before reporting completion

he-maintainer/SKILL.md

@@ -66,6 +66,18 @@ Depending on the request, create or update one or more of:
 
 Prefer short, maintainable files over one giant document.
 
+## Target-repo file roles
+
+Use these roles by default:
+
+- `AGENTS.md`: the shortest practical working guide; key commands, constraints, and major repo structure
+- `ai/project-map.md`: directory responsibilities, entrypoints, and important data or control flow notes
+- `ai/task-templates.md`: reusable task request formats for bugfix, feature, refactor, migration, and test-writing work
+- `ai/risk-guardrails.md`: high-risk areas, forbidden changes, slow validations, generated files, and deployment-sensitive zones
+- `ai/harness-health.md`: current harness audit snapshot and next improvement priorities
+
+If the repo is small, keep most content in `AGENTS.md` and delay the extra files until needed.
+
 ## Update policy
 
 Prefer targeted edits over full rewrites.