harness-everything 0.2.0

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

@@ -0,0 +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

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

@@ -0,0 +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.)

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

@@ -0,0 +1,83 @@
+---
+name: "knowledge-readme-template"
+description: "Dynamic README template for documentation, knowledge bases, and courseware. Uses conditional {{IF feature}} blocks based on detected repository capabilities (e.g., learning paths, agentic workspaces)."
+---
+
+# {Project Name}
+
+> {One-line description summarizing the core subject or purpose of this knowledge base.}
+
+<!-- Optional: badges for version, license, or status -->
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+## Overview & Scope
+
+{2–4 sentences explaining what this repository covers, who it is for, and how the information is structured. Be specific about the domain (e.g., "This repository contains the architectural analysis of OpenClaw...").}
+
+---
+
+{{IF has_learning_path}}
+## Start Here / Learning Path
+
+{Provide a brief guide on how a reader should navigate this repository based on the detected `roadmap.md`, `study-guide.md`, or sequential file naming.}
+
+- **[Step 1 Title](./path/to/file.md)**: {Brief description}
+- **[Step 2 Title](./path/to/file.md)**: {Brief description}
+{{ENDIF}}
+
+---
+
+## Knowledge Directory
+
+{Organize the discovered markdown directories into thematic groups. Do not just print a raw file tree. Group them logically.}
+
+### 📂 {Thematic Group 1: e.g., Core Subsystems}
+{1 sentence describing what's in this group.}
+- [`{dir_name}/`](./path/) - {Brief description based on contents}
+- [`{dir_name}/`](./path/) - {Brief description based on contents}
+
+### 📚 {Thematic Group 2: e.g., Reference Materials}
+{1 sentence describing what's in this group.}
+- [`{dir_name}/`](./path/) - {Brief description}
+
+---
+
+{{IF is_agentic_workspace}}
+## AI Agent Workspace
+
+This repository is an **Agentic Workspace**. It is actively managed and interacted with by AI agents, not just human readers.
+
+### Active Agents
+{List the detected agents from `.github/agents/` or `AGENTS.md`.}
+- **`{Agent Name}`**: {Briefly describe what this agent does based on its file name/content.}
+
+### Agent Workflows
+{Briefly explain how humans interact with the agents in this repo. E.g., "Add a task to `tasks/backlog.json` and the Orchestrator will assign it to a sub-agent. Check `logs/` for execution results."}
+{{ENDIF}}
+
+---
+
+{{IF has_task_tracking}}
+## Project Status & Tasks
+
+{Describe how progress is tracked in this repository based on `STATUS.md`, `tasks/`, or backlog files.}
+
+- **Current Status**: {Extract key point from STATUS.md if available, else omit}
+- **Task Board**: Found in [`tasks/`](./tasks/).
+{{ENDIF}}
+
+---
+
+{{PRESERVED_HUMAN_CONTENT}}
+<!-- AI AGENT INSTRUCTION: If the original README contained domain-specific teaching materials, tutorials, long-form explanations, or extensive deep-dive sections (e.g., "Performance vs Scalability", "System Architecture", etc.), they MUST be preserved here. Do not discard instructional prose! -->
+
+---
+
+## Contributing
+
+Want to contribute to this knowledge base?
+{If `is_agentic_workspace` is true, remind users to check `AGENTS.md` before making massive structural changes. If false, just provide a standard PR message.}
+
+## License
+
+{License name} — see [LICENSE](LICENSE) for details.

package/repo-docs/templates/manual-recon.md

@@ -0,0 +1,117 @@
+---
+name: "manual-recon"
+description: "Bash commands for manual repository reconnaissance when python scripts are unavailable."
+---
+
+# Manual Recon Steps
+
+Use these bash commands when `recon.py` is not available.
+Run each block and collect the output before generating docs.
+
+## 1. Directory tree
+
+```bash
+# macOS / Linux (depth 3, ignoring noise)
+find . -maxdepth 3 \
+  -not -path '*/node_modules/*' \
+  -not -path '*/.git/*' \
+  -not -path '*/__pycache__/*' \
+  -not -path '*/.venv/*' \
+  -not -path '*/dist/*' \
+  -not -path '*/build/*' \
+  -not -path '*/.next/*' \
+  -not -path '*/target/*' \
+  | sort
+```
+
+## 2. Project identity
+
+```bash
+# Node
+cat package.json | python3 -c "
+import json,sys; d=json.load(sys.stdin)
+print('name:', d.get('name'))
+print('description:', d.get('description'))
+print('version:', d.get('version'))
+print('license:', d.get('license'))
+print('scripts:', list(d.get('scripts',{}).keys()))
+print('engines:', d.get('engines'))
+"
+
+# Python
+cat pyproject.toml 2>/dev/null || cat setup.py 2>/dev/null
+
+# Rust
+cat Cargo.toml 2>/dev/null
+
+# Go
+cat go.mod 2>/dev/null
+```
+
+## 3. Package manager
+
+```bash
+ls package-lock.json yarn.lock pnpm-lock.yaml bun.lockb 2>/dev/null
+```
+
+## 4. Scripts / Makefile
+
+```bash
+# Node scripts
+cat package.json | python3 -c "
+import json,sys; d=json.load(sys.stdin)
+for k,v in d.get('scripts',{}).items(): print(f'  {k}: {v}')
+"
+
+# Makefile targets
+grep -E '^[a-zA-Z_-]+:' Makefile 2>/dev/null | head -30
+```
+
+## 5. Runtime versions
+
+```bash
+cat .nvmrc 2>/dev/null
+cat .node-version 2>/dev/null
+cat .python-version 2>/dev/null
+cat .tool-versions 2>/dev/null
+```
+
+## 6. CI commands
+
+```bash
+grep -h "run:" .github/workflows/*.yml 2>/dev/null | head -30
+```
+
+## 7. Existing docs
+
+```bash
+cat README.md 2>/dev/null
+cat AGENTS.md 2>/dev/null
+```
+
+## 8. Key config files (check presence)
+
+```bash
+ls \
+  jest.config.* vitest.config.* \
+  .eslintrc* eslint.config.* \
+  .prettierrc* prettier.config.* \
+  ruff.toml .ruff.toml \
+  turbo.json nx.json pnpm-workspace.yaml \
+  Dockerfile docker-compose.yml \
+  2>/dev/null
+```
+
+## 9. Dependency hints (detect framework)
+
+```bash
+# Node — check for common frameworks
+cat package.json | python3 -c "
+import json,sys; d=json.load(sys.stdin)
+all_deps = {**d.get('dependencies',{}), **d.get('devDependencies',{})}
+frameworks = ['next','nuxt','remix','astro','vite','express','fastify','nestjs',
+              'react','vue','svelte','solid','angular','electron','tauri']
+found = [f for f in frameworks if f in all_deps or f+'js' in all_deps]
+print('detected frameworks:', found)
+"
+```

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

@@ -0,0 +1,72 @@
+---
+name: "multi-skills-readme-template"
+description: "README template for a repository hosting a collection of AI skills. Focuses on design philosophy, quickstart, and categorized skills with workflow dependencies."
+---
+
+# {Project Name / Skill Collection}
+
+> {One-line pitch: E.g., A collection of composable, engineering-focused AI skills.}
+
+<!-- Optional: Badges for version, license, status -->
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+## Overview & Philosophy
+
+{2–3 paragraphs explaining *why* this collection exists. What common AI coding failures (e.g., verbosity, architectural rot, misalignment) does this pack solve? Explain the design principles behind these skills.}
+
+---
+
+## Quickstart
+
+{How to install or activate the entire pack of skills in the user's environment. E.g., `npx skills@latest add ...` or cloning the repo.}
+
+```bash
+{installation command}
+```
+
+---
+
+## Core Problem Statements & Solutions
+
+{Identify 2-3 common failure modes when working with AI, and highlight which skills in this repository solve them.}
+
+### Problem: {e.g., The Agent Didn't Do What I Want}
+**The Fix**: Use `/{skill-name}` to {briefly describe the solution workflow}.
+
+---
+
+## Skills Directory
+
+{List the skills grouped by their categories. For each category, emphasize workflow dependencies or sequential requirements.}
+
+### {Category 1: e.g., Engineering}
+
+{1-2 sentences summarizing what this category of skills does.}
+
+> **Workflow & Dependencies**:
+> - **Required Setup**: {e.g., Run `/setup-project` before using any other skills in this category.}
+> - **Suggested Flow**: {e.g., Use `/to-prd` to design -> `/to-issues` to split tasks -> `/tdd` to implement.}
+
+| Skill | Description | Link |
+|---|---|---|
+| `{skill-name}` | {Description from YAML frontmatter} | [View Skill](./skills/category/{skill-name}/SKILL.md) |
+| `{skill-name-2}` | {Description from YAML frontmatter} | [View Skill](./skills/category/{skill-name-2}/SKILL.md) |
+
+### {Category 2: e.g., Productivity}
+
+{1-2 sentences summarizing what this category of skills does.}
+
+| Skill | Description | Link |
+|---|---|---|
+| `{skill-name}` | {Description from YAML frontmatter} | [View Skill](./skills/category/{skill-name}/SKILL.md) |
+
+---
+
+## Contributing & Authoring
+
+Want to add a new skill to this repository? 
+{Provide brief instructions or link to a `/write-a-skill` guideline.}
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE) for details.

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

@@ -0,0 +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."}