harness-everything 0.2.2 → 0.4.0

package/repo-docs/templates/agents-template.md

@@ -1,264 +1,264 @@
----
-name: "agents-template"
-description: "Canonical AGENTS.md template with archetype-aware section selection."
----
-
-# AGENTS.md Template
-
-Terse, directive. Every section should be machine-readable.
-No filler. No prose padding. Commands must be exact and copy-pasteable.
-
----
-
-## Archetype-Aware Structure
-
-The sections to include depend on the repository archetype (from Step 0 of the skill
-workflow). For `code` repos, use the full template below. For other archetypes, replace
-the **Commands** block with **Workflows & Commands** and use the relevant non-code
-template at the end of this file.
-
-| Archetype | Commands block | Extra sections |
-|---|---|---|
-| **`code`** | Full `## Commands` with setup/dev/test/lint/build | Architecture, Conventions, Do Not Edit, Gotchas |
-| **`product`** | `## Development Commands` (Setup, Dev, Test, Build) | Tech Stack, Domain Knowledge Mapping, System Boundaries |
-| **`single-skill`**| `## Commands` (Testing, Linting) | See [`skills-agents-template.md`](skills-agents-template.md) (Taxonomy, Extension Rules, Schema) |
-| **`multi-skills`**| `## Commands` (Authoring, Linking, Linting) | See [`skills-agents-template.md`](skills-agents-template.md) (Taxonomy, Extension Rules, Schema) |
-| **`docs/courseware`**| `## Editing Rules & Formatting` | See [`knowledge-agents-template.md`](knowledge-agents-template.md) (Agentic Workflows, Task States) |
-| **`docs`** | `## Workflows & Commands` (build, preview, publish) | Page Tree, Authoring Rules, Style Conventions |
-| **`hybrid`** | Combine applicable blocks | Combine relevant extra sections |
-
----
-
-## Code Archetype Template
-
-```markdown
-# {project_name}
-
-{One tight paragraph: what it is, primary language/framework, notable architecture
-decisions. No marketing language.}
-
-## Commands
-
-### Setup
-```bash
-{install command}        # first-time setup
-{env setup command}      # e.g., cp .env.example .env
-```
-
-### Development
-```bash
-{dev server command}     # starts local dev environment
-```
-
-### Testing
-```bash
-{run all tests}
-{run single test file}   # e.g., pnpm test src/foo.test.ts
-{run with coverage}
-```
-
-### Lint & Format
-```bash
-{lint command}
-{format command}         # auto-fix
-```
-
-### Build
-```bash
-{build command}
-{build output location}  # e.g., outputs to dist/
-```
-
-## Architecture
-
-```
-{key directories only}
-```
-
-| Directory | Purpose |
-|---|---|
-| `src/` | {description} |
-| `tests/` | {description} |
-| `scripts/` | {description} |
-| ... | ... |
-
-{2–3 sentences on any non-obvious architecture decisions an AI should know about.}
-
-## Conventions
-
-- **Language/runtime**: {e.g., TypeScript strict mode, Python 3.11+}
-- **Imports**: {e.g., absolute imports from `src/`, no relative `../..`}
-- **Naming**: {e.g., camelCase functions, PascalCase components, kebab-case files}
-- **Style**: {link to or summarize eslint/ruff/prettier config highlights}
-- **Tests**: {e.g., co-located `.test.ts` files, fixtures in `tests/fixtures/`}
-- **Env vars**: {list required env vars and where to get them}
-
-## Do Not Edit
-
-- `{generated file or dir}` — auto-generated, do not edit manually
-- `{lock file}` — managed by {tool}
-- `{vendor or build dir}` — output only
-
-## Gotchas
-
-- {Any non-obvious behaviour that would trip up an AI agent}
-- {e.g., "pnpm only — npm and yarn will break workspace resolution"}
-- {e.g., "Tests require a running Postgres instance on port 5432"}
-- {e.g., "The `src/generated/` directory is committed but auto-generated by `pnpm codegen`"}
-```
-
----
-
-## Non-Code Archetype Templates
-
-Use the relevant block below as a starting point for non-`code` repos.
-
-### Skills Library
-
-```markdown
-# {project_name}
-
-{One tight paragraph: what this collection is, how many skills it contains, and which
-AI platforms it targets.}
-
-## Workflows & Commands
-
-### Add a skill
-```bash
-# Create a new SKILL.md at the correct path
-mkdir -p skills/{category}/{skill-name}
-# Then create skills/{category}/{skill-name}/SKILL.md with required frontmatter
-```
-
-### Link skills (if applicable)
-```bash
-{link command, e.g., bash scripts/link-skills.sh}
-```
-
-### Validate frontmatter
-```bash
-{lint command, or: manually verify name, description fields are present}
-```
-
-## Skills Inventory
-
-| Category | Skill | Description |
-|---|---|---|
-| `{category}` | `{name}` | {description} |
-
-## Authoring Rules
-
-- **Frontmatter**: Every `SKILL.md` must have `name` and `description` fields.
-- **Trigger phrases**: Write `description` to match how a user would ask for the skill.
-- **File placement**: `skills/{category}/{skill-name}/SKILL.md`
-- **Naming**: `{skill-name}` is kebab-case; `{category}` is kebab-case.
-
-## Do Not Edit
-
-- {generated index files, if any}
-```
-
----
-
-### Courseware
-
-```markdown
-# {project_name}
-
-{One tight paragraph: what this course teaches, primary audience, and tech stack.}
-
-## Workflows & Commands
-
-### Scaffold a new exercise
-```bash
-mkdir -p exercises/{XX}-{section-name}/{XX}.{YY}-{exercise-name}/{explainer,problem,solution}
-```
-
-### Lint exercises
-```bash
-{lint command, e.g., pnpm ai-hero-cli internal lint}
-```
-
-### Commit with history preservation
-```bash
-git mv exercises/{old-path} exercises/{new-path}  # use git mv, never plain mv
-```
-
-## Exercise Structure
-
-```
-exercises/
-  {XX}-{section-name}/
-    {XX}.{YY}-{exercise-name}/
-      explainer/   # conceptual material — no TODOs
-      problem/     # student workspace with TODOs
-      solution/    # reference implementation
-```
-
-## Naming Conventions
-
-- Sections: `XX-section-name/` (two-digit zero-padded prefix, dash-case)
-- Exercises: `XX.YY-exercise-name/` (section.exercise prefix, dash-case)
-- Each subfolder must contain a non-empty `readme.md`
-
-## Lint Rules Summary
-
-- Each exercise needs at least one of `problem/`, `explainer/`, or `solution/`
-- `readme.md` must exist and be non-empty in each subfolder
-- No `.gitkeep` files; no broken links in readmes
-
-## Do Not Edit
-
-- {generated files, if any}
-```
-
----
-
-### Documentation Site
-
-```markdown
-# {project_name}
-
-{One tight paragraph: what this docs site covers, the tool used (GitBook, MkDocs, etc.),
-and where the live site is published.}
-
-## Workflows & Commands
-
-### Preview locally
-```bash
-{preview command, e.g., gitbook serve, mkdocs serve}
-```
-
-### Build / publish
-```bash
-{build or deploy command}
-```
-
-## Documentation Structure
-
-```
-{abbreviated page tree}
-```
-
-## Authoring Rules
-
-- {naming conventions for .md files}
-- {where to place images/assets}
-- {required frontmatter, if any}
-- {style guide highlights}
-
-## Do Not Edit
-
-- {generated nav files, build output dirs}
-```
-
----
-
-## Style rules for AGENTS.md
-
-- **Imperative** sentences: "Run X to do Y" not "You can run X..."
-- **No intros or sign-offs** — agents don't need greetings
-- All commands must be runnable as-is in a terminal (no pseudocode)
-- If a command varies by OS, show both: `# macOS / Linux` and `# Windows`
-- Be explicit about what NOT to do — agents benefit from guardrails
-- List env vars agents will need; never embed secrets
+---
+name: "agents-template"
+description: "Canonical AGENTS.md template with archetype-aware section selection."
+---
+
+# AGENTS.md Template
+
+Terse, directive. Every section should be machine-readable.
+No filler. No prose padding. Commands must be exact and copy-pasteable.
+
+---
+
+## Archetype-Aware Structure
+
+The sections to include depend on the repository archetype (from Step 0 of the skill
+workflow). For `code` repos, use the full template below. For other archetypes, replace
+the **Commands** block with **Workflows & Commands** and use the relevant non-code
+template at the end of this file.
+
+| Archetype | Commands block | Extra sections |
+|---|---|---|
+| **`code`** | Full `## Commands` with setup/dev/test/lint/build | Architecture, Conventions, Do Not Edit, Gotchas |
+| **`product`** | `## Development Commands` (Setup, Dev, Test, Build) | Tech Stack, Domain Knowledge Mapping, System Boundaries |
+| **`single-skill`**| `## Commands` (Testing, Linting) | See [`skills-agents-template.md`](skills-agents-template.md) (Taxonomy, Extension Rules, Schema) |
+| **`multi-skills`**| `## Commands` (Authoring, Linking, Linting) | See [`skills-agents-template.md`](skills-agents-template.md) (Taxonomy, Extension Rules, Schema) |
+| **`docs/courseware`**| `## Editing Rules & Formatting` | See [`knowledge-agents-template.md`](knowledge-agents-template.md) (Agentic Workflows, Task States) |
+| **`docs`** | `## Workflows & Commands` (build, preview, publish) | Page Tree, Authoring Rules, Style Conventions |
+| **`hybrid`** | Combine applicable blocks | Combine relevant extra sections |
+
+---
+
+## Code Archetype Template
+
+```markdown
+# {project_name}
+
+{One tight paragraph: what it is, primary language/framework, notable architecture
+decisions. No marketing language.}
+
+## Commands
+
+### Setup
+```bash
+{install command}        # first-time setup
+{env setup command}      # e.g., cp .env.example .env
+```
+
+### Development
+```bash
+{dev server command}     # starts local dev environment
+```
+
+### Testing
+```bash
+{run all tests}
+{run single test file}   # e.g., pnpm test src/foo.test.ts
+{run with coverage}
+```
+
+### Lint & Format
+```bash
+{lint command}
+{format command}         # auto-fix
+```
+
+### Build
+```bash
+{build command}
+{build output location}  # e.g., outputs to dist/
+```
+
+## Architecture
+
+```
+{key directories only}
+```
+
+| Directory | Purpose |
+|---|---|
+| `src/` | {description} |
+| `tests/` | {description} |
+| `scripts/` | {description} |
+| ... | ... |
+
+{2–3 sentences on any non-obvious architecture decisions an AI should know about.}
+
+## Conventions
+
+- **Language/runtime**: {e.g., TypeScript strict mode, Python 3.11+}
+- **Imports**: {e.g., absolute imports from `src/`, no relative `../..`}
+- **Naming**: {e.g., camelCase functions, PascalCase components, kebab-case files}
+- **Style**: {link to or summarize eslint/ruff/prettier config highlights}
+- **Tests**: {e.g., co-located `.test.ts` files, fixtures in `tests/fixtures/`}
+- **Env vars**: {list required env vars and where to get them}
+
+## Do Not Edit
+
+- `{generated file or dir}` — auto-generated, do not edit manually
+- `{lock file}` — managed by {tool}
+- `{vendor or build dir}` — output only
+
+## Gotchas
+
+- {Any non-obvious behaviour that would trip up an AI agent}
+- {e.g., "pnpm only — npm and yarn will break workspace resolution"}
+- {e.g., "Tests require a running Postgres instance on port 5432"}
+- {e.g., "The `src/generated/` directory is committed but auto-generated by `pnpm codegen`"}
+```
+
+---
+
+## Non-Code Archetype Templates
+
+Use the relevant block below as a starting point for non-`code` repos.
+
+### Skills Library
+
+```markdown
+# {project_name}
+
+{One tight paragraph: what this collection is, how many skills it contains, and which
+AI platforms it targets.}
+
+## Workflows & Commands
+
+### Add a skill
+```bash
+# Create a new SKILL.md at the correct path
+mkdir -p skills/{category}/{skill-name}
+# Then create skills/{category}/{skill-name}/SKILL.md with required frontmatter
+```
+
+### Link skills (if applicable)
+```bash
+{link command, e.g., bash scripts/link-skills.sh}
+```
+
+### Validate frontmatter
+```bash
+{lint command, or: manually verify name, description fields are present}
+```
+
+## Skills Inventory
+
+| Category | Skill | Description |
+|---|---|---|
+| `{category}` | `{name}` | {description} |
+
+## Authoring Rules
+
+- **Frontmatter**: Every `SKILL.md` must have `name` and `description` fields.
+- **Trigger phrases**: Write `description` to match how a user would ask for the skill.
+- **File placement**: `skills/{category}/{skill-name}/SKILL.md`
+- **Naming**: `{skill-name}` is kebab-case; `{category}` is kebab-case.
+
+## Do Not Edit
+
+- {generated index files, if any}
+```
+
+---
+
+### Courseware
+
+```markdown
+# {project_name}
+
+{One tight paragraph: what this course teaches, primary audience, and tech stack.}
+
+## Workflows & Commands
+
+### Scaffold a new exercise
+```bash
+mkdir -p exercises/{XX}-{section-name}/{XX}.{YY}-{exercise-name}/{explainer,problem,solution}
+```
+
+### Lint exercises
+```bash
+{lint command, e.g., pnpm ai-hero-cli internal lint}
+```
+
+### Commit with history preservation
+```bash
+git mv exercises/{old-path} exercises/{new-path}  # use git mv, never plain mv
+```
+
+## Exercise Structure
+
+```
+exercises/
+  {XX}-{section-name}/
+    {XX}.{YY}-{exercise-name}/
+      explainer/   # conceptual material — no TODOs
+      problem/     # student workspace with TODOs
+      solution/    # reference implementation
+```
+
+## Naming Conventions
+
+- Sections: `XX-section-name/` (two-digit zero-padded prefix, dash-case)
+- Exercises: `XX.YY-exercise-name/` (section.exercise prefix, dash-case)
+- Each subfolder must contain a non-empty `readme.md`
+
+## Lint Rules Summary
+
+- Each exercise needs at least one of `problem/`, `explainer/`, or `solution/`
+- `readme.md` must exist and be non-empty in each subfolder
+- No `.gitkeep` files; no broken links in readmes
+
+## Do Not Edit
+
+- {generated files, if any}
+```
+
+---
+
+### Documentation Site
+
+```markdown
+# {project_name}
+
+{One tight paragraph: what this docs site covers, the tool used (GitBook, MkDocs, etc.),
+and where the live site is published.}
+
+## Workflows & Commands
+
+### Preview locally
+```bash
+{preview command, e.g., gitbook serve, mkdocs serve}
+```
+
+### Build / publish
+```bash
+{build or deploy command}
+```
+
+## Documentation Structure
+
+```
+{abbreviated page tree}
+```
+
+## Authoring Rules
+
+- {naming conventions for .md files}
+- {where to place images/assets}
+- {required frontmatter, if any}
+- {style guide highlights}
+
+## Do Not Edit
+
+- {generated nav files, build output dirs}
+```
+
+---
+
+## Style rules for AGENTS.md
+
+- **Imperative** sentences: "Run X to do Y" not "You can run X..."
+- **No intros or sign-offs** — agents don't need greetings
+- All commands must be runnable as-is in a terminal (no pseudocode)
+- If a command varies by OS, show both: `# macOS / Linux` and `# Windows`
+- Be explicit about what NOT to do — agents benefit from guardrails
+- List env vars agents will need; never embed secrets

package/repo-docs/templates/knowledge-agents-template.md

@@ -1,50 +1,50 @@
----
-name: "knowledge-agents-template"
-description: "Dynamic AGENTS.md template for documentation, knowledge bases, and courseware. Uses conditional {{IF feature}} blocks based on detected capabilities to provide either basic editing rules or strict agentic workflows."
----
-
-# {Project Name} - AI Authoring & Operations Guide
-
-> This document serves as the machine-readable instruction manual for AI agents operating within this documentation/knowledge repository.
-
-## Editing Rules & Formatting
-
-When tasked with generating or modifying content in this repository, strictly adhere to the following rules:
-
-- **Style conventions**: {e.g., Use H2 and H3 for sub-sections. Do not use H1 except for the main title.}
-- **Language & Tone**: {e.g., Professional and academic. If the repo is multi-lingual, ensure you modify the correct file.}
-- **Structural Integrity**: This repository relies on a specific sequence (e.g., numbered prefixes like `01-`, `02-`). **Do not rename or reorder files** unless explicitly instructed to reorganize the curriculum.
-
----
-
-{{IF is_agentic_workspace}}
-## Agentic Operations & Workflows
-
-This repository is an active Agentic Workspace. You must interact with the established agent ecosystem correctly.
-
-### Workflow & Task Management
-- **Task Intake**: New tasks are generally found in `tasks/backlog.json` or as markdown specs in `tasks/specs/`.
-- **State Management**: When beginning a task, move it or track its state in the `tasks/active/` directory. Upon completion, log the result in `tasks/completed/`.
-- **Logging**: All major generation runs must be documented. Create a timestamped folder in `logs/runs/{timestamp}/` detailing the input prompt, token usage, and output summary.
-
-### Inter-Agent Collaboration
-Do not attempt to perform tasks assigned to resident sub-agents.
-- If content needs verification, defer to the existing `quality-validator.agent.md` or `fact-check-scout.agent.md`.
-- Review the `.github/agents/` folder to understand your peers' capabilities before executing complex multi-step generations.
-{{ENDIF}}
-
----
-
-{{IF has_task_tracking}}
-## Status Updates
-
-If you make significant additions to the knowledge base:
-- You **MUST** update `STATUS.md` or the corresponding `backlog` file to reflect the completion of the topic.
-{{ENDIF}}
-
----
-
-## Do Not Edit
-
-- `{Generated index files, e.g., _sidebar.md}` (Managed by {tool, e.g., Docsify})
-- `logs/runs/` (Append-only. Never modify historical logs.)
+---
+name: "knowledge-agents-template"
+description: "Dynamic AGENTS.md template for documentation, knowledge bases, and courseware. Uses conditional {{IF feature}} blocks based on detected capabilities to provide either basic editing rules or strict agentic workflows."
+---
+
+# {Project Name} - AI Authoring & Operations Guide
+
+> This document serves as the machine-readable instruction manual for AI agents operating within this documentation/knowledge repository.
+
+## Editing Rules & Formatting
+
+When tasked with generating or modifying content in this repository, strictly adhere to the following rules:
+
+- **Style conventions**: {e.g., Use H2 and H3 for sub-sections. Do not use H1 except for the main title.}
+- **Language & Tone**: {e.g., Professional and academic. If the repo is multi-lingual, ensure you modify the correct file.}
+- **Structural Integrity**: This repository relies on a specific sequence (e.g., numbered prefixes like `01-`, `02-`). **Do not rename or reorder files** unless explicitly instructed to reorganize the curriculum.
+
+---
+
+{{IF is_agentic_workspace}}
+## Agentic Operations & Workflows
+
+This repository is an active Agentic Workspace. You must interact with the established agent ecosystem correctly.
+
+### Workflow & Task Management
+- **Task Intake**: New tasks are generally found in `tasks/backlog.json` or as markdown specs in `tasks/specs/`.
+- **State Management**: When beginning a task, move it or track its state in the `tasks/active/` directory. Upon completion, log the result in `tasks/completed/`.
+- **Logging**: All major generation runs must be documented. Create a timestamped folder in `logs/runs/{timestamp}/` detailing the input prompt, token usage, and output summary.
+
+### Inter-Agent Collaboration
+Do not attempt to perform tasks assigned to resident sub-agents.
+- If content needs verification, defer to the existing `quality-validator.agent.md` or `fact-check-scout.agent.md`.
+- Review the `.github/agents/` folder to understand your peers' capabilities before executing complex multi-step generations.
+{{ENDIF}}
+
+---
+
+{{IF has_task_tracking}}
+## Status Updates
+
+If you make significant additions to the knowledge base:
+- You **MUST** update `STATUS.md` or the corresponding `backlog` file to reflect the completion of the topic.
+{{ENDIF}}
+
+---
+
+## Do Not Edit
+
+- `{Generated index files, e.g., _sidebar.md}` (Managed by {tool, e.g., Docsify})
+- `logs/runs/` (Append-only. Never modify historical logs.)