harness-everything 0.2.1 → 0.3.6

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

@@ -1,78 +1,78 @@
----
-name: "product-agents-template"
-description: "AGENTS.md template for end-user products (Full-stack apps, CLI tools, SaaS platforms). Provides AI agents with precise architecture, commands, conventions, and domain knowledge."
----
-
-# {Product Name} - AI Developer Guide
-
-> {One tight paragraph: technical summary of the product. E.g., "A full-stack React/Node.js application using PostgreSQL and MCP for agentic queries. Monorepo structure managed by pnpm." No marketing language.}
-
-## Tech Stack & Architecture
-
-- **Frontend**: {Framework, styling, state management. e.g., Next.js App Router, Tailwind, Zustand}
-- **Backend**: {Language, framework. e.g., Node.js, Express/Hono}
-- **Database**: {Database type and ORM. e.g., PostgreSQL via Prisma}
-
-```
-{abbreviated tree — key directories only}
-```
-
-| Directory | Purpose |
-|---|---|
-| `apps/frontend/` | {description} |
-| `apps/api/` | {description} |
-| `packages/core/` | {description} |
-
-## Development Commands
-
-All commands are executed from the repository root unless otherwise noted.
-
-### Setup & Database
-```bash
-{install command e.g., pnpm install}
-{env setup e.g., cp .env.example .env}
-{database migration e.g., pnpm db:push}
-```
-
-### Local Development
-```bash
-{dev server command e.g., pnpm run dev}
-```
-- Frontend runs on: `http://localhost:{port}`
-- API runs on: `http://localhost:{port}`
-
-### Testing & Linting
-```bash
-{test command e.g., pnpm test}
-{lint command e.g., pnpm lint}
-```
-
-### Build
-```bash
-{build command e.g., pnpm build}
-```
-
-## Conventions
-
-- **Package Manager**: {e.g., Strictly use `pnpm`. `npm` and `yarn` will break resolution.}
-- **Imports**: {e.g., Use absolute imports from `@/` in the frontend.}
-- **Naming**: {e.g., PascalCase for React components, kebab-case for file names.}
-- **State**: {e.g., Use Zustand for global state, avoid React Context unless necessary.}
-
-## Product Domain Knowledge
-
-{Briefly map product terminology to code concepts to help AI understand the business logic.}
-- **{Domain Term 1}**: Handled entirely in `packages/core/src/term-1.ts`.
-- **{Domain Term 2}**: Corresponds to the `Term2` database model in the Prisma schema.
-
-## Do Not Edit
-
-- `{generated file or dir}` — Auto-generated, do not edit manually.
-- `{lock file}` — Managed by {tool} (e.g., `pnpm-lock.yaml`).
-- `{build output dir}` — Ephemeral output.
-
-## System Boundaries & Gotchas
-
-- {Constraint 1: e.g., "The API server strictly requires the `DATABASE_URL` environment variable to start."}
-- {Constraint 2: e.g., "Do not modify the `lib/generated/` folder; it is built on the fly during `pnpm dev`."}
-- {Constraint 3: e.g., "If adding a new database table, you must run `pnpm db:generate` before testing."}
+---
+name: "product-agents-template"
+description: "AGENTS.md template for end-user products (Full-stack apps, CLI tools, SaaS platforms). Provides AI agents with precise architecture, commands, conventions, and domain knowledge."
+---
+
+# {Product Name} - AI Developer Guide
+
+> {One tight paragraph: technical summary of the product. E.g., "A full-stack React/Node.js application using PostgreSQL and MCP for agentic queries. Monorepo structure managed by pnpm." No marketing language.}
+
+## Tech Stack & Architecture
+
+- **Frontend**: {Framework, styling, state management. e.g., Next.js App Router, Tailwind, Zustand}
+- **Backend**: {Language, framework. e.g., Node.js, Express/Hono}
+- **Database**: {Database type and ORM. e.g., PostgreSQL via Prisma}
+
+```
+{abbreviated tree — key directories only}
+```
+
+| Directory | Purpose |
+|---|---|
+| `apps/frontend/` | {description} |
+| `apps/api/` | {description} |
+| `packages/core/` | {description} |
+
+## Development Commands
+
+All commands are executed from the repository root unless otherwise noted.
+
+### Setup & Database
+```bash
+{install command e.g., pnpm install}
+{env setup e.g., cp .env.example .env}
+{database migration e.g., pnpm db:push}
+```
+
+### Local Development
+```bash
+{dev server command e.g., pnpm run dev}
+```
+- Frontend runs on: `http://localhost:{port}`
+- API runs on: `http://localhost:{port}`
+
+### Testing & Linting
+```bash
+{test command e.g., pnpm test}
+{lint command e.g., pnpm lint}
+```
+
+### Build
+```bash
+{build command e.g., pnpm build}
+```
+
+## Conventions
+
+- **Package Manager**: {e.g., Strictly use `pnpm`. `npm` and `yarn` will break resolution.}
+- **Imports**: {e.g., Use absolute imports from `@/` in the frontend.}
+- **Naming**: {e.g., PascalCase for React components, kebab-case for file names.}
+- **State**: {e.g., Use Zustand for global state, avoid React Context unless necessary.}
+
+## Product Domain Knowledge
+
+{Briefly map product terminology to code concepts to help AI understand the business logic.}
+- **{Domain Term 1}**: Handled entirely in `packages/core/src/term-1.ts`.
+- **{Domain Term 2}**: Corresponds to the `Term2` database model in the Prisma schema.
+
+## Do Not Edit
+
+- `{generated file or dir}` — Auto-generated, do not edit manually.
+- `{lock file}` — Managed by {tool} (e.g., `pnpm-lock.yaml`).
+- `{build output dir}` — Ephemeral output.
+
+## System Boundaries & Gotchas
+
+- {Constraint 1: e.g., "The API server strictly requires the `DATABASE_URL` environment variable to start."}
+- {Constraint 2: e.g., "Do not modify the `lib/generated/` folder; it is built on the fly during `pnpm dev`."}
+- {Constraint 3: e.g., "If adding a new database table, you must run `pnpm db:generate` before testing."}

package/repo-docs/templates/product-readme-template.md

@@ -1,95 +1,95 @@
----
-name: "product-readme-template"
-description: "README template for end-user products, tools, applications, or platforms. Focuses on the user journey, deployment, and usage rather than source code compilation."
----
-
-# {Product Name}
-
-> {One-line pitch: What it is and the primary problem it solves.}
-
-<!-- Optional: Badges for version, license, status, discord -->
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-
-## Overview
-
-{2–3 sentences explaining what the product does, who it's for, and why they should care. Focus on the value delivered, not the tech stack.}
-
----
-
-## Typical Use Cases
-
-- **{Use Case 1}**: {Describe a specific real-world scenario where a user would apply this product to solve a problem.}
-- **{Use Case 2}**: {e.g., "Onboarding: New engineers query the knowledge base instead of reading thousands of commits."}
-
----
-
-## Getting Started
-
-### Prerequisites
-- {e.g., Docker, Node.js, specific OS requirements}
-- {Any required API keys or external accounts}
-
-### Installation / Deployment
-```bash
-# E.g., Docker run command, or download link instructions
-docker run -d -p 8080:8080 my-product/latest
-```
-
-### Initial Configuration
-{1-2 steps to configure the bare minimum to get it running, e.g., setting up the `.env` file or initial login.}
-
----
-
-## Core Workflow & Features
-
-{Walk the user through their first "Aha!" moment. How do they actually use the product?}
-
-### 1. {Step One: e.g., Ingestion / Connection}
-{Explanation and command/screenshot}
-
-### 2. {Step Two: e.g., Processing / Analysis}
-{Explanation and command/screenshot}
-
-### 3. {Step Three: e.g., Querying / Results}
-{Explanation and command/screenshot}
-
----
-
-## Concepts & Glossary
-
-| Term | Definition |
-|---|---|
-| `{Term 1}` | {Plain English explanation of specific product terminology} |
-| `{Term 2}` | {Explanation} |
-
----
-
-## Security & Privacy
-
-{Critical for AI or data-heavy products. Explain where data goes, how keys are stored, and if any third-party telemetry or LLM training is involved.}
-
-- **Data Locality:** {e.g., Everything runs locally, no code is sent to the cloud except via explicit LLM prompts.}
-- **Credentials:** {e.g., API keys are stored encrypted in the local SQLite database.}
-
----
-
-## FAQ & Limitations
-
-- **Q: {Common question or error}**
-  - **A:** {Solution or workaround}
-
-- **Known Limitation:** {e.g., Currently only supports repositories under 2GB.}
-
----
-
-## Support & Community
-
-- Need help? Open an [Issue](https://github.com/...).
-- Join our community on [Discord/Slack](#).
-
----
-
-## For Developers
-
-Want to build `{Product Name}` from source or contribute? 
-Please see our [Contributing Guide](CONTRIBUTING.md) and the AI instructions in [`AGENTS.md`](AGENTS.md).
+---
+name: "product-readme-template"
+description: "README template for end-user products, tools, applications, or platforms. Focuses on the user journey, deployment, and usage rather than source code compilation."
+---
+
+# {Product Name}
+
+> {One-line pitch: What it is and the primary problem it solves.}
+
+<!-- Optional: Badges for version, license, status, discord -->
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+## Overview
+
+{2–3 sentences explaining what the product does, who it's for, and why they should care. Focus on the value delivered, not the tech stack.}
+
+---
+
+## Typical Use Cases
+
+- **{Use Case 1}**: {Describe a specific real-world scenario where a user would apply this product to solve a problem.}
+- **{Use Case 2}**: {e.g., "Onboarding: New engineers query the knowledge base instead of reading thousands of commits."}
+
+---
+
+## Getting Started
+
+### Prerequisites
+- {e.g., Docker, Node.js, specific OS requirements}
+- {Any required API keys or external accounts}
+
+### Installation / Deployment
+```bash
+# E.g., Docker run command, or download link instructions
+docker run -d -p 8080:8080 my-product/latest
+```
+
+### Initial Configuration
+{1-2 steps to configure the bare minimum to get it running, e.g., setting up the `.env` file or initial login.}
+
+---
+
+## Core Workflow & Features
+
+{Walk the user through their first "Aha!" moment. How do they actually use the product?}
+
+### 1. {Step One: e.g., Ingestion / Connection}
+{Explanation and command/screenshot}
+
+### 2. {Step Two: e.g., Processing / Analysis}
+{Explanation and command/screenshot}
+
+### 3. {Step Three: e.g., Querying / Results}
+{Explanation and command/screenshot}
+
+---
+
+## Concepts & Glossary
+
+| Term | Definition |
+|---|---|
+| `{Term 1}` | {Plain English explanation of specific product terminology} |
+| `{Term 2}` | {Explanation} |
+
+---
+
+## Security & Privacy
+
+{Critical for AI or data-heavy products. Explain where data goes, how keys are stored, and if any third-party telemetry or LLM training is involved.}
+
+- **Data Locality:** {e.g., Everything runs locally, no code is sent to the cloud except via explicit LLM prompts.}
+- **Credentials:** {e.g., API keys are stored encrypted in the local SQLite database.}
+
+---
+
+## FAQ & Limitations
+
+- **Q: {Common question or error}**
+  - **A:** {Solution or workaround}
+
+- **Known Limitation:** {e.g., Currently only supports repositories under 2GB.}
+
+---
+
+## Support & Community
+
+- Need help? Open an [Issue](https://github.com/...).
+- Join our community on [Discord/Slack](#).
+
+---
+
+## For Developers
+
+Want to build `{Product Name}` from source or contribute? 
+Please see our [Contributing Guide](CONTRIBUTING.md) and the AI instructions in [`AGENTS.md`](AGENTS.md).

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

@@ -1,136 +1,136 @@
----
-name: "readme-template"
-description: "Canonical README.md template with archetype-aware section selection."
----
-
-# README.md Template
-
-Use this as a structural guide. Omit sections gracefully when info isn't available.
-Write in prose — avoid excessive bullets.
-
----
-
-## Archetype-Aware Section Selection
-
-Choose the section set that matches the repository archetype (from Step 0 of the skill
-workflow). Never leave empty section headings — skip sections that don't apply.
-
-| Archetype | Include | Skip |
-|---|---|---|
-| **`code`** | All sections in the full template below | — |
-| **`product`** | See [`product-readme-template.md`](product-readme-template.md) for full layout (Overview, Getting Started, Workflow, FAQ, etc.) | Build, Test, Debugging, Packaging (moved to AGENTS.md) |
-| **`single-skill`**| See [`single-skill-readme-template.md`](single-skill-readme-template.md) for full layout (Usage, Workflow, Constraints, Resources) | Installation, Build, Test, Debugging |
-| **`multi-skills`**| See [`multi-skills-readme-template.md`](multi-skills-readme-template.md) for full layout (Philosophy, Categorized Directory, Workflows) | Installation, Build, Test, Debugging, Packaging |
-| **`courseware`** | Title, Overview, Course Structure, Prerequisites, How to Run Exercises, Contributing, License | Build, Debugging, Packaging |
-| **`docs`** | Title, Overview, Documentation Structure, How to Contribute Docs, Build / Publish (if applicable), License | Test, Debugging, Packaging |
-| **`hybrid`** | Combine applicable columns; add a "What's in this Repo" orientation section first | Empty sections |
-
-### Non-code section templates
-
-**Skills Index** — for `skills` repos:
-```markdown
-## Skills
-
-| Name | Description |
-|---|---|
-| `{skill_name}` | {description from frontmatter} |
-```
-
-**Course Structure** — for `courseware` repos:
-```markdown
-## Course Structure
-
-| Section | Exercises |
-|---|---|
-| `{XX}-{section-name}` | {exercise names} |
-```
-
-**Documentation Structure** — for `docs` repos:
-```markdown
-## Documentation Structure
-
-{abbreviated page tree — top-level sections with one-line descriptions}
-```
-
----
-
-## Full Template (code archetype)
-
-```markdown
-# {project_name}
-
-> {one_line_description}
-
-<!-- Optional: badges for language, license, CI status -->
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-
-## Overview
-
-{2–4 sentences explaining what the project does, who it's for, and what problem
-it solves. Write this as a human would, not a spec sheet.}
-
-## Prerequisites
-
-- {Runtime}: {version} (e.g., Node.js ≥ 20, Python ≥ 3.11)
-- {Any other hard requirements}
-
-## Installation
-
-```bash
-{package_manager} install
-# or: pip install -e .
-```
-
-## Usage
-
-```bash
-{primary run command}
-```
-
-{One-paragraph description of basic usage, or a short example if helpful.}
-
-## Project Structure
-
-```
-{abbreviated tree — top-level dirs only, one-line description each}
-```
-
-## Development
-
-### Running tests
-
-```bash
-{test command}
-```
-
-### Linting & formatting
-
-```bash
-{lint command}
-{format command}
-```
-
-### Building
-
-```bash
-{build command}
-```
-
-## Contributing
-
-{Brief note or link to CONTRIBUTING.md. One or two sentences is enough.}
-
-## License
-
-{License name} — see [LICENSE](LICENSE) for details.
-```
-
----
-
-## Style notes
-
-- Use `##` for top-level sections (not `#`)
-- Code blocks must specify language: ` ```bash `, ` ```ts `, etc.
-- Don't add sections you can't populate — an empty section is worse than no section
-- Keep the Overview honest — don't oversell
-- Version numbers must match what's in the config files exactly
+---
+name: "readme-template"
+description: "Canonical README.md template with archetype-aware section selection."
+---
+
+# README.md Template
+
+Use this as a structural guide. Omit sections gracefully when info isn't available.
+Write in prose — avoid excessive bullets.
+
+---
+
+## Archetype-Aware Section Selection
+
+Choose the section set that matches the repository archetype (from Step 0 of the skill
+workflow). Never leave empty section headings — skip sections that don't apply.
+
+| Archetype | Include | Skip |
+|---|---|---|
+| **`code`** | All sections in the full template below | — |
+| **`product`** | See [`product-readme-template.md`](product-readme-template.md) for full layout (Overview, Getting Started, Workflow, FAQ, etc.) | Build, Test, Debugging, Packaging (moved to AGENTS.md) |
+| **`single-skill`**| See [`single-skill-readme-template.md`](single-skill-readme-template.md) for full layout (Usage, Workflow, Constraints, Resources) | Installation, Build, Test, Debugging |
+| **`multi-skills`**| See [`multi-skills-readme-template.md`](multi-skills-readme-template.md) for full layout (Philosophy, Categorized Directory, Workflows) | Installation, Build, Test, Debugging, Packaging |
+| **`courseware`** | Title, Overview, Course Structure, Prerequisites, How to Run Exercises, Contributing, License | Build, Debugging, Packaging |
+| **`docs`** | Title, Overview, Documentation Structure, How to Contribute Docs, Build / Publish (if applicable), License | Test, Debugging, Packaging |
+| **`hybrid`** | Combine applicable columns; add a "What's in this Repo" orientation section first | Empty sections |
+
+### Non-code section templates
+
+**Skills Index** — for `skills` repos:
+```markdown
+## Skills
+
+| Name | Description |
+|---|---|
+| `{skill_name}` | {description from frontmatter} |
+```
+
+**Course Structure** — for `courseware` repos:
+```markdown
+## Course Structure
+
+| Section | Exercises |
+|---|---|
+| `{XX}-{section-name}` | {exercise names} |
+```
+
+**Documentation Structure** — for `docs` repos:
+```markdown
+## Documentation Structure
+
+{abbreviated page tree — top-level sections with one-line descriptions}
+```
+
+---
+
+## Full Template (code archetype)
+
+```markdown
+# {project_name}
+
+> {one_line_description}
+
+<!-- Optional: badges for language, license, CI status -->
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+## Overview
+
+{2–4 sentences explaining what the project does, who it's for, and what problem
+it solves. Write this as a human would, not a spec sheet.}
+
+## Prerequisites
+
+- {Runtime}: {version} (e.g., Node.js ≥ 20, Python ≥ 3.11)
+- {Any other hard requirements}
+
+## Installation
+
+```bash
+{package_manager} install
+# or: pip install -e .
+```
+
+## Usage
+
+```bash
+{primary run command}
+```
+
+{One-paragraph description of basic usage, or a short example if helpful.}
+
+## Project Structure
+
+```
+{abbreviated tree — top-level dirs only, one-line description each}
+```
+
+## Development
+
+### Running tests
+
+```bash
+{test command}
+```
+
+### Linting & formatting
+
+```bash
+{lint command}
+{format command}
+```
+
+### Building
+
+```bash
+{build command}
+```
+
+## Contributing
+
+{Brief note or link to CONTRIBUTING.md. One or two sentences is enough.}
+
+## License
+
+{License name} — see [LICENSE](LICENSE) for details.
+```
+
+---
+
+## Style notes
+
+- Use `##` for top-level sections (not `#`)
+- Code blocks must specify language: ` ```bash `, ` ```ts `, etc.
+- Don't add sections you can't populate — an empty section is worse than no section
+- Keep the Overview honest — don't oversell
+- Version numbers must match what's in the config files exactly