harness-everything 0.2.2 → 0.3.6

package/references/performance-checklist.md

@@ -0,0 +1,153 @@
+# Performance Checklist
+
+Quick reference checklist for web application performance. Use alongside the `performance-optimization` skill.
+
+## Table of Contents
+
+- [Core Web Vitals Targets](#core-web-vitals-targets)
+- [TTFB Diagnosis](#ttfb-diagnosis)
+- [Frontend Checklist](#frontend-checklist)
+- [Backend Checklist](#backend-checklist)
+- [Measurement Commands](#measurement-commands)
+- [Common Anti-Patterns](#common-anti-patterns)
+
+## Core Web Vitals Targets
+
+| Metric | Good | Needs Work | Poor |
+|--------|------|------------|------|
+| LCP (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
+| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
+| CLS (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
+
+## TTFB Diagnosis
+
+When TTFB is slow (> 800ms), check each component in DevTools Network waterfall:
+
+- [ ] **DNS resolution** slow → add `<link rel="dns-prefetch">` or `<link rel="preconnect">` for known origins
+- [ ] **TCP/TLS handshake** slow → enable HTTP/2, consider edge deployment, verify keep-alive
+- [ ] **Server processing** slow → profile backend, check slow queries, add caching
+
+## Frontend Checklist
+
+### Images
+- [ ] Images use modern formats (WebP, AVIF)
+- [ ] Images are responsively sized (`srcset` and `sizes`)
+- [ ] Images and `<source>` elements have explicit `width` and `height` (prevents CLS in art direction)
+- [ ] Below-the-fold images use `loading="lazy"` and `decoding="async"`
+- [ ] Hero/LCP images use `fetchpriority="high"` and no lazy loading
+
+### JavaScript
+- [ ] Bundle size under 200KB gzipped (initial load)
+- [ ] Code splitting with dynamic `import()` for routes and heavy features
+- [ ] Tree shaking enabled (verify dependency ships ESM and marks `sideEffects: false`)
+- [ ] No blocking JavaScript in `<head>` (use `defer` or `async`)
+- [ ] Heavy computation offloaded to Web Workers (if applicable)
+- [ ] `React.memo()` on expensive components that re-render with same props
+- [ ] `useMemo()` / `useCallback()` only where profiling shows benefit
+- [ ] Long tasks (> 50ms) broken up to keep the main thread available — main lever for INP
+- [ ] `yieldToMain` pattern used inside long-running loops so input events can run between chunks
+- [ ] Modern scheduling APIs used where available: `scheduler.yield()` (preferred), `scheduler.postTask()` with priorities, `isInputPending()` to yield only when needed
+- [ ] `requestIdleCallback` for deferrable, non-urgent work (analytics flush, prefetch, warmup)
+- [ ] Non-critical work deferred out of event handlers (e.g. analytics, logging) so the response to the interaction is not delayed
+- [ ] Third-party scripts loaded with `async` / `defer`, audited for size, and fronted by a facade when heavy (chat widgets, embeds)
+
+### CSS
+- [ ] Critical CSS inlined or preloaded
+- [ ] No render-blocking CSS for non-critical styles
+- [ ] No CSS-in-JS runtime cost in production (use extraction)
+
+### Fonts
+- [ ] Limited to 2–3 font families, 2–3 weights each (every additional weight is another request)
+- [ ] WOFF2 format only (smallest, universal support — skip WOFF/TTF/EOT)
+- [ ] Self-hosted when possible (third-party font CDNs add DNS + TCP + TLS round-trips)
+- [ ] LCP-critical fonts preloaded: `<link rel="preload" as="font" type="font/woff2" crossorigin>`
+- [ ] `font-display: swap` (or `optional` for non-critical) to avoid FOIT blocking render
+- [ ] Subsetted via `unicode-range` to ship only the glyphs each page needs
+- [ ] Variable fonts considered when multiple weights/styles are required (one file replaces many)
+- [ ] Fallback font metrics adjusted with `size-adjust`, `ascent-override`, `descent-override` to reduce CLS on font swap
+- [ ] System font stack considered before any custom font
+
+### Network
+- [ ] Static assets cached with long `max-age` + content hashing
+- [ ] API responses cached where appropriate (`Cache-Control`)
+- [ ] HTTP/2 or HTTP/3 enabled
+- [ ] Resources preconnected (`<link rel="preconnect">`) for known origins
+- [ ] `fetchpriority` used on critical non-image resources (e.g., key `<link rel="preload">`, above-the-fold `<script>`) — not only on `<img>`
+- [ ] No unnecessary redirects
+
+### Rendering
+- [ ] No layout thrashing (forced synchronous layouts)
+- [ ] Animations use `transform` and `opacity` (GPU-accelerated)
+- [ ] Long lists use virtualization (e.g., `react-window`)
+- [ ] No unnecessary full-page re-renders
+- [ ] Off-screen sections use `content-visibility: auto` with `contain-intrinsic-size` to skip layout/paint of non-visible areas
+- [ ] No `unload` event handlers and no `Cache-Control: no-store` on HTML responses — preserves back/forward cache (bfcache) eligibility
+
+## Backend Checklist
+
+### Database
+- [ ] No N+1 query patterns (use eager loading / joins)
+- [ ] Queries have appropriate indexes
+- [ ] List endpoints paginated (never `SELECT * FROM table`)
+- [ ] Connection pooling configured
+- [ ] Slow query logging enabled
+
+### API
+- [ ] Response times < 200ms (p95)
+- [ ] No synchronous heavy computation in request handlers
+- [ ] Bulk operations instead of loops of individual calls
+- [ ] Response compression (gzip/brotli)
+- [ ] Appropriate caching (in-memory, Redis, CDN)
+
+### Infrastructure
+- [ ] CDN for static assets
+- [ ] Server located close to users (or edge deployment)
+- [ ] Horizontal scaling configured (if needed)
+- [ ] Health check endpoint for load balancer
+
+## Measurement Commands
+
+### INP field data and DevTools workflow
+
+1. **Field data first** — check [CrUX Vis](https://developer.chrome.com/docs/crux/vis) or your RUM tool for real-user INP before optimising
+2. **Identify slow interactions** — open DevTools → Performance panel → record while interacting; look for long tasks triggered by clicks/keystrokes
+3. **Test on mid-range Android** — INP issues often only surface on slower hardware; use a real device or DevTools CPU throttling (4×–6× slowdown)
+
+```bash
+# Lighthouse CLI
+npx lighthouse https://localhost:3000 --output json --output-path ./report.json
+
+# Bundle analysis
+npx webpack-bundle-analyzer stats.json
+# or for Vite:
+npx vite-bundle-visualizer
+
+# Check bundle size
+npx bundlesize
+
+# Web Vitals in code
+import { onLCP, onINP, onCLS } from 'web-vitals';
+onLCP(console.log);
+onINP(console.log);
+onCLS(console.log);
+
+# INP with interaction-level detail (attribution build)
+import { onINP } from 'web-vitals/attribution';
+onINP(({ value, attribution }) => {
+  const { interactionTarget, inputDelay, processingDuration, presentationDelay } = attribution;
+  console.log({ value, interactionTarget, inputDelay, processingDuration, presentationDelay });
+});
+```
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Impact | Fix |
+|---|---|---|
+| N+1 queries | Linear DB load growth | Use joins, includes, or batch loading |
+| Unbounded queries | Memory exhaustion, timeouts | Always paginate, add LIMIT |
+| Missing indexes | Slow reads as data grows | Add indexes for filtered/sorted columns |
+| Layout thrashing | Jank, dropped frames | Batch DOM reads, then batch writes |
+| Unoptimized images | Slow LCP, wasted bandwidth | Use WebP, responsive sizes, lazy load |
+| Large bundles | Slow Time to Interactive | Code split, tree shake, audit deps |
+| Blocking main thread | Poor INP, unresponsive UI | Chunk long tasks with `scheduler.yield()` / `yieldToMain`, offload to Web Workers |
+| Memory leaks | Growing memory, eventual crash | Clean up listeners, intervals, refs |

package/references/platform-advisory-template.md

@@ -0,0 +1,58 @@
+# Harness OS Guidance (Advisory)
+
+This file provides standardized advisory guidance for AI coding agents across all platforms.
+For Claude Code users, this guidance is enforced via lifecycle hooks (hard enforcement).
+For other platforms (Cursor, Copilot, Codex, Continue.dev, Hermes Agent), this is advisory only.
+
+## Environment Alignment (Discovery over Assumption)
+
+Before executing any command:
+1. Detect your active shell (bash, zsh, PowerShell, cmd, fish)
+2. Detect your operating system (Windows, macOS, Linux)
+3. Detect your package manager (npm, yarn, pnpm, bun, pip, cargo)
+4. Use only commands compatible with your detected environment
+
+## Circuit Breaker Rule (Rule of 3)
+
+If you encounter the same error 3 times:
+1. **STOP.** Do not attempt a 4th variation.
+2. Re-read the error message carefully - don't guess what it says.
+3. Check the actual file contents (don't assume you know them).
+4. Consider: is this a syntax error, logic error, environment issue, or missing dependency?
+5. Try a fundamentally different approach.
+6. If still stuck after reflection, escalate to your Human Partner with a clear decision request.
+
+## Context Preservation (Anti-Bloat Protection)
+
+- Avoid reading large files unnecessarily
+- When output exceeds 500 lines, summarize key sections
+- Prefer targeted searches (grep/glob) over reading entire files
+- Clean up temporary files and outputs when done
+
+## Self-Evolution (Continuous Workspace Memory)
+
+When you resolve a complex issue:
+1. Reflect on the root cause
+2. Extract the lesson as a concise rule
+3. Consider if this should be added to workspace rules
+4. Prevent future regression by documenting the pattern
+
+## Verification Discipline
+
+Before claiming a change works:
+1. Run the actual tests (don't just read the code)
+2. Verify the fix works in isolation
+3. Check for unintended side effects
+4. Confirm the solution addresses the root cause, not just symptoms
+
+## Token Efficiency
+
+- Prefer targeted fixes over broad rewrites
+- Use read-only tools (Read/Grep/Glob) before mutating tools
+- Verify assumptions before implementing solutions
+- Avoid unnecessary context loading
+
+---
+
+*This template ensures consistent guidance across all AI coding platforms.*
+*For hard enforcement on Claude Code, see the lifecycle hooks in .claude/settings.json.*

package/references/security-checklist.md

@@ -0,0 +1,205 @@
+# Security Checklist
+
+Quick reference for web application security. Use alongside the `security-and-hardening` skill.
+
+## Table of Contents
+
+- [Threat Modeling (Start Here)](#threat-modeling-start-here)
+- [Pre-Commit Checks](#pre-commit-checks)
+- [Authentication](#authentication)
+- [Authorization](#authorization)
+- [Input Validation](#input-validation)
+- [Security Headers](#security-headers)
+- [CORS Configuration](#cors-configuration)
+- [Data Protection](#data-protection)
+- [Dependency Security](#dependency-security)
+- [AI / LLM Security](#ai--llm-security)
+- [Error Handling](#error-handling)
+- [OWASP Top 10 Quick Reference](#owasp-top-10-quick-reference)
+- [OWASP Top 10 for LLMs Quick Reference](#owasp-top-10-for-llms-quick-reference)
+
+## Threat Modeling (Start Here)
+
+Before reaching for controls, spend five minutes thinking like an attacker:
+
+- [ ] Trust boundaries mapped (requests, uploads, webhooks, third-party APIs, LLM output)
+- [ ] Assets named (credentials, PII, payment data, admin actions, money movement)
+- [ ] STRIDE run per boundary (Spoofing, Tampering, Repudiation, Info disclosure, DoS, Elevation)
+- [ ] Abuse cases written next to use cases ("how would I misuse this?")
+
+## Pre-Commit Checks
+
+- [ ] No secrets in code (`git diff --cached | grep -i "password\|secret\|api_key\|token"`)
+- [ ] `.gitignore` covers: `.env`, `.env.local`, `*.pem`, `*.key`
+- [ ] `.env.example` uses placeholder values (not real secrets)
+
+## Authentication
+
+- [ ] Passwords hashed with bcrypt (≥12 rounds), scrypt, or argon2
+- [ ] Session cookies: `httpOnly`, `secure`, `sameSite: 'lax'`
+- [ ] Session expiration configured (reasonable max-age)
+- [ ] Rate limiting on login endpoint (≤10 attempts per 15 minutes)
+- [ ] Password reset tokens: time-limited (≤1 hour), single-use
+- [ ] Account lockout after repeated failures (optional, with notification)
+- [ ] MFA supported for sensitive operations (optional but recommended)
+
+## Authorization
+
+- [ ] Every protected endpoint checks authentication
+- [ ] Every resource access checks ownership/role (prevents IDOR)
+- [ ] Admin endpoints require admin role verification
+- [ ] API keys scoped to minimum necessary permissions
+- [ ] JWT tokens validated (signature, expiration, issuer)
+
+## Input Validation
+
+- [ ] All user input validated at system boundaries (API routes, form handlers)
+- [ ] Validation uses allowlists (not denylists)
+- [ ] String lengths constrained (min/max)
+- [ ] Numeric ranges validated
+- [ ] Email, URL, and date formats validated with proper libraries
+- [ ] File uploads: type restricted, size limited, content verified
+- [ ] SQL queries parameterized (no string concatenation)
+- [ ] HTML output encoded (use framework auto-escaping)
+- [ ] URLs validated before redirect (prevent open redirect)
+- [ ] Server-side URL fetches allowlisted; private/reserved IPs blocked (prevent SSRF)
+
+## Security Headers
+
+```
+Content-Security-Policy: default-src 'self'; script-src 'self'
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+X-XSS-Protection: 0  (disabled, rely on CSP)
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+## CORS Configuration
+
+```typescript
+// Restrictive (recommended)
+cors({
+  origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
+  credentials: true,
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+  allowedHeaders: ['Content-Type', 'Authorization'],
+})
+
+// NEVER use in production:
+cors({ origin: '*' })  // Allows any origin
+```
+
+## Data Protection
+
+- [ ] Sensitive fields excluded from API responses (`passwordHash`, `resetToken`, etc.)
+- [ ] Sensitive data not logged (passwords, tokens, full CC numbers)
+- [ ] PII encrypted at rest (if required by regulation)
+- [ ] HTTPS for all external communication
+- [ ] Database backups encrypted
+
+## Dependency Security
+
+First locate the **installation boundary**. If the package is matched by a parent `workspaces` declaration, use that workspace root; otherwise use the nearest project root that owns both its manifest and dependency graph. At that boundary, corroborate `packageManager` (when present), the lockfile, and CI commands. Stop if they disagree or competing manager lockfiles exist there. A nested project is independent only when it is outside the parent workspace; independent subprojects may legitimately use different managers.
+
+| Manager/version signal | Frozen/immutable CI install | Known-advisory audit |
+|---|---|---|
+| npm (`package-lock.json` or `npm-shrinkwrap.json`) | `npm ci` | `npm audit` |
+| pnpm | `pnpm install --frozen-lockfile` | `pnpm audit` |
+| Yarn 2+ | `yarn install --immutable` | `yarn npm audit -A -R` |
+| Yarn 1 | `yarn install --frozen-lockfile` | `yarn audit` |
+
+For an unlisted manager or version, consult its official documentation; do not substitute another manager's commands or newer defaults.
+
+### Install-Script Gate
+
+Never discover dependency lifecycle scripts by first executing an ordinary install on a client whose defaults have not been verified.
+
+1. Bootstrap with dependency scripts disabled, or with a documented default-deny policy plus fail-closed enforcement.
+2. Inspect the exact script source and package version before approval.
+3. Record the narrowest native allow/deny policy at the installation boundary and commit it.
+4. Run a clean frozen/immutable install with that policy and verify the required packages still build.
+
+**Point-in-time snapshot:** Package-manager defaults and command names change quickly. Verify this matrix against the pinned client's current official documentation before relying on it.
+
+| Manager version | Native policy |
+|---|---|
+| npm without verified granular approvals | Bootstrap with `npm ci --ignore-scripts`, or persist `ignore-scripts=true` when project-wide blocking is intended. Keep scripts disabled or deliberately upgrade before allowing any reviewed dependency script. |
+| npm 11.18.x (verified on 11.18.0) | Unreviewed dependency scripts run with a warning by default. Enforce `strict-allow-scripts=true` before a normal install, then use the workspace-unaware `npm install-scripts ls` from the installation boundary; keep approvals version-pinned and denials name-wide. |
+| npm 12.x (verified on 12.0.1) | Unreviewed dependency scripts are skipped by default; `strict-allow-scripts=true` makes their presence fail the install before execution. Use the same `npm install-scripts` review and approval flow. |
+| pnpm 11+ | Use `pnpm approve-builds` and commit `allowBuilds` decisions; `strictDepBuilds` defaults to `true`, so unreviewed builds fail. |
+| pnpm 10.26–10.x | Configure `allowBuilds` explicitly, or use `pnpm approve-builds` with the legacy `onlyBuiltDependencies` / `ignoredBuiltDependencies` lists. Set `strictDepBuilds: true`; its v10 default is `false`. |
+| pnpm 10.1–10.25 | `pnpm approve-builds` records the legacy lists; enable `strictDepBuilds` where supported (10.3+). |
+| Older or unknown pnpm | Bootstrap with `pnpm install --frozen-lockfile --ignore-scripts`. Keep scripts disabled unless the pinned version documents an enforceable policy. |
+| Yarn 4.14+ | Dependency postinstalls are disabled by default. Grant only required exceptions with top-level `dependenciesMeta.<package>.built: true`. |
+| Yarn 2–4.13 | Set `enableScripts: false` in `.yarnrc.yml`, then grant only required exceptions with top-level `dependenciesMeta.<package>.built: true`; do not enable scripts globally. |
+| Yarn 1 | Bootstrap with `yarn install --ignore-scripts`; keep scripts disabled unless each required exception is reviewed under the pinned client's documented workflow. |
+
+Authoritative checks: [npm install-scripts](https://docs.npmjs.com/cli/v11/commands/npm-install-scripts/), [install policy](https://docs.npmjs.com/cli/v11/commands/npm-install/), and [CLI releases](https://github.com/npm/cli/releases); [pnpm approve-builds](https://pnpm.io/cli/approve-builds) and [build settings](https://pnpm.io/settings#allowbuilds); [Yarn security](https://yarnpkg.com/features/security) and [manifest](https://yarnpkg.com/configuration/manifest#dependenciesMeta).
+
+**Supply-chain hygiene** (advisory audits do not catch newly malicious packages):
+- [ ] Exactly one authoritative lockfile per project/workspace root is committed and CI never rewrites it
+- [ ] Critical/high findings are triaged for reachability; deferrals have a reason and review date
+- [ ] Forced audit remediation (`npm audit fix --force` or equivalent) is never automatic; remediation diffs and changelogs are reviewed
+- [ ] Registry signatures/provenance are verified where the manager supports it
+- [ ] Dependency lifecycle scripts are blocked before first execution and approved only through the pinned manager's native policy
+- [ ] New dependencies are reviewed for ownership, maintenance, release age, provenance, transitive graph, and typosquatting
+
+## AI / LLM Security
+
+For any feature that calls an LLM (chatbots, summarizers, agents, RAG):
+
+- [ ] Model output treated as untrusted — never into `eval`/SQL/shell/`innerHTML`/file paths
+- [ ] Prompt injection assumed; permissions enforced in code, not in the system prompt
+- [ ] Secrets, cross-tenant data, and full system prompts kept out of the context window
+- [ ] Tool/agent permissions scoped; destructive or irreversible actions require confirmation
+- [ ] Token, rate, and recursion/loop limits set (bound consumption)
+
+## Error Handling
+
+```typescript
+// Production: generic error, no internals
+res.status(500).json({
+  error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' }
+});
+
+// NEVER in production:
+res.status(500).json({
+  error: err.message,
+  stack: err.stack,         // Exposes internals
+  query: err.sql,           // Exposes database details
+});
+```
+
+## OWASP Top 10 Quick Reference
+
+| # | Vulnerability | Prevention |
+|---|---|---|
+| 1 | Broken Access Control | Auth checks on every endpoint, ownership verification |
+| 2 | Cryptographic Failures | HTTPS, strong hashing, no secrets in code |
+| 3 | Injection | Parameterized queries, input validation |
+| 4 | Insecure Design | Threat modeling, spec-driven development |
+| 5 | Security Misconfiguration | Security headers, minimal permissions, audit deps |
+| 6 | Vulnerable Components | The ecosystem's dependency audit (`npm audit`, `pip-audit`, ...), keep deps updated, minimal deps |
+| 7 | Auth Failures | Strong passwords, rate limiting, session management |
+| 8 | Data Integrity Failures | Verify updates/dependencies, signed artifacts |
+| 9 | Logging Failures | Log security events, don't log secrets |
+| 10 | SSRF | Validate/allowlist URLs, restrict outbound requests |
+
+## OWASP Top 10 for LLMs Quick Reference
+
+For apps with LLM features. See the [OWASP GenAI Security Project](https://genai.owasp.org/llm-top-10/).
+
+| ID | Risk | Prevention |
+|---|---|---|
+| LLM01 | Prompt Injection | Don't trust the system prompt as a boundary; enforce permissions in code |
+| LLM02 | Sensitive Information Disclosure | Keep secrets/PII out of prompts; filter outputs |
+| LLM03 | Supply Chain | Vet models, datasets, and plugins like any dependency |
+| LLM04 | Data and Model Poisoning | Use trusted model sources, verify integrity; vet fine-tuning and RAG data |
+| LLM05 | Improper Output Handling | Treat model output as untrusted; validate, parameterize, encode |
+| LLM06 | Excessive Agency | Scope tool permissions; confirm destructive actions |
+| LLM07 | System Prompt Leakage | Assume the system prompt can leak; put no secrets in it |
+| LLM08 | Vector and Embedding Weaknesses | Partition RAG embeddings per tenant; validate documents before indexing |
+| LLM09 | Misinformation | Ground answers with citations; validate critical claims; keep a human in the loop |
+| LLM10 | Unbounded Consumption | Cap tokens, request rate, and loop/recursion depth |

package/repo-docs/SKILL.md

@@ -1,45 +1,46 @@
 ---
 name: repo-docs
-description: Automatically generates precise, reader-oriented README.md and AGENTS.md based on actual project scans.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: Generate or update precise, reader-oriented README.md and AGENTS.md based on actual project scans and smart merging of existing files. Use when a project lacks documentation or needs refreshed agent onboarding docs.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.4
 ---
 
-# Repo Docs (Automated Project Documentation Generation)
+# Repo Docs (Automated Project Documentation Generation & Smart Merging)
 
-## 📋 Skill Contract
+Merges codebase scan facts and bespoke notes into `README.md`/`AGENTS.md`.
+
+## USE FOR:
+- Generate README.md for undocumented projects
+- Update AGENTS.md after structural changes
+- Merge legacy notes into refreshed docs
+
+## DO NOT USE FOR:
+- Marketing copy not grounded in codebase scans
+- Fabricating docs without scanning the repo
+- Non-repository documents (wikis)
+
+## Skill Contract
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | Project lacks documentation, or the user requests a `README.md` / `AGENTS.md` / architectural guideline be generated. |
-| **Expected Output** | A reader-journey-oriented `README.md` and/or agent-oriented `AGENTS.md`, built from the appropriate template in `repo-docs/templates/`. |
-| **State Mutations** | Creates/overwrites `README.md`, `AGENTS.md`, or other doc files at the target path. |
-| **Enforcement Gate** | **MUST NOT** be written from training-data assumptions — every claim (language, framework, test/build commands) **MUST** come from actually scanning the project. Uncertain parts **MUST** be marked `// TODO: Pending confirmation` and raised to the human, not guessed. |
-
-Triggered when a project lacks documentation, the user requests to create a `README.md`, or needs to define architectural guidelines in `AGENTS.md`.
-
-## 1. Reconnaissance & Environment Discovery `[Discover]`
-- **Fabrication Prohibited**: You absolutely MUST NOT rely on the model's historical training data to write documentation.
-- Call scripts or use `grep_search`, `read_file` to scan project directories, dependency files like `package.json`, `Cargo.toml`, etc.
-- Confirm the project's language, framework, test commands, and deployment methods.
-
-## 2. Organization & Writing `[Think] & [Try]`
-- **Reader-Oriented**: If generating a `README.md`, the content MUST focus on the "User Journey": what this product does, how to install it, how to use core features.
-- If generating `AGENTS.md` or developer guidelines: The content MUST focus on "architectural conventions, build commands, test commands" for future AI Agents (or human developers) to read.
-- **Combine with Cognitive Loop**: When writing, obey the `install-cognitive-os` rules, predict the chapter structure of the document first, generate it in one go, and leave room for future expansion.
-
-## 3. Verification & Alignment `[Summarize]`
-- After generating the document, you MUST ensure the installation or test commands within the document are **actually executable**.
-- If there are uncertain parts, leave `// TODO: Pending confirmation` markers in the document and ask the human questions (`grill-me` mode).
-
-## Deep Reference Templates
-To ensure professional quality, you MUST use the appropriate template from `repo-docs/templates/`:
-- `repo-docs/templates/readme-template.md` — Standard project documentation template
-- `repo-docs/templates/product-readme-template.md` — Product archetype user-journey template
-- `repo-docs/templates/multi-skills-readme-template.md` — Large project with multiple skills/modules
-- `repo-docs/templates/knowledge-readme-template.md` — Information-heavy/knowledge-base template
-- `repo-docs/templates/agents-template.md` — Standard agent onboarding instructions template
-- `repo-docs/templates/product-agents-template.md` — Agent instructions for product repositories
-- `repo-docs/templates/skills-agents-template.md` — Agent instructions for skills repositories
-- `repo-docs/templates/knowledge-agents-template.md` — Agent instructions for knowledge/research projects
-- `repo-docs/templates/manual-recon.md` — Methodology for manual repo scanning and classification
+| **Trigger / Input** | Missing docs; request to update `README.md`/`AGENTS.md`. |
+| **Expected Output** | `README.md`/`AGENTS.md` merging scan facts + bespoke notes. |
+| **State Mutations** | Updates `README.md`/`AGENTS.md` or fallbacks; preserves human docs. |
+| **Enforcement Gate** | Inspect existing docs first; preserve bespoke notes while upgrading structure. |
+
+## Workflow
+
+1. [Discover] Scan configs (`package.json`, `Cargo.toml`) as Source of Truth. Never fabricate.
+2. Read existing docs fully first; extract bespoke notes (env vars, URLs, gotchas); never overwrite blindly.
+3. Pick a template below; else built-in structure.
+4. Draft: `README.md` = user journey; `AGENTS.md` = conventions, build/test commands.
+5. [Summarize] Verify commands run; mark doubts `// TODO: Pending confirmation`; ask (`grill-me`).
+6. Write to root; if protected, `.github/AGENTS.md`/`docs/README.md`.
+
+## `repo-docs/templates/`
+
+readme-template.md · product-readme-template.md · multi-skills-readme-template.md · single-skill-readme-template.md · knowledge-readme-template.md · agents-template.md · product-agents-template.md · skills-agents-template.md · knowledge-agents-template.md · manual-recon.md
+
+Deep dive: references/process-guide.md

package/repo-docs/references/process-guide.md

@@ -0,0 +1,60 @@
+# Process Guide (Deep Dive)
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Generate / Update README.md or AGENTS.md] --> Scan[1. Scan Codebase Files: package.json, Cargo.toml, src/]
+    Scan --> CheckExisting{2. Existing Target File Found?}
+    
+    CheckExisting -- Yes --> ReadOld[Read Existing File & Extract Bespoke Notes<br>custom env vars, deployment URLs, manual FAQs]
+    CheckExisting -- No --> SelectTemplate{3. Template Selection}
+    
+    ReadOld --> SelectTemplate
+    
+    SelectTemplate -- Template Files Readable --> ReadTemplate[Read repo-docs/templates/*.md]
+    SelectTemplate -- Directory Unreachable --> StandardFallback[Use Built-in Standard Template Structure]
+    
+    ReadTemplate --> Draft[4. Draft & Smartly Merge Documentation<br>Codebase Facts + Extracted Bespoke Notes + Template Structure]
+    StandardFallback --> Draft
+    
+    Draft --> VerifyCommands[5. Cross-check Executable Commands Against Configs]
+    VerifyCommands --> CheckRoot{6. Resolve Storage Location}
+    
+    CheckRoot -- Root Writable --> WriteRoot[Save / Merge to README.md or AGENTS.md at Root]
+    CheckRoot -- Protected Root --> WritePlatform[Write to .github/AGENTS.md or docs/README.md]
+    
+    WriteRoot --> Done[Documentation Smartly Updated]
+    WritePlatform --> Done
+```
+
+## 1. Reconnaissance & Smart Preservation `[Discover]`
+- **Fabrication Prohibited**: You absolutely MUST NOT rely on the model's historical training data to write documentation.
+- **Smart Preservation & Merging (DO NOT Blindly Overwrite)**:
+  - If a `README.md` or `AGENTS.md` already exists, use `read_file` to read it completely before making edits.
+  - Extract bespoke human-written notes that cannot be inferred from code scans alone (e.g. proprietary deployment URLs, custom environment variables, historical architectural trade-offs, or legacy gotchas).
+  - Blend these bespoke notes into the newly structured template layout.
+- Call scripts or use `grep_search`, `read_file` to scan project directories and dependency files (`package.json`, `Cargo.toml`, `.env.example`, etc.).
+- Confirm the project's real language, framework, test commands, and deployment methods. Codebase configs always serve as the Single Source of Truth over outdated prose in old README files.
+
+## 2. Organization & Writing `[Think] & [Try]`
+- **Reader-Oriented**: If generating a `README.md`, the content MUST focus on the "User Journey": what this product does, how to install it, how to use core features.
+- If generating `AGENTS.md` or developer guidelines: The content MUST focus on "architectural conventions, build commands, test commands" for future AI Agents (or human developers) to read.
+- **Combine with Cognitive Loop**: When writing, obey the `install-cognitive-os` rules, predict the chapter structure of the document first, generate it in one go, and leave room for future expansion.
+
+## 3. Verification & Alignment `[Summarize]`
+- After generating the document, you MUST ensure the installation or test commands within the document are **actually executable**.
+- If there are uncertain parts, leave `// TODO: Pending confirmation` markers in the document and ask the human questions (`grill-me` mode).
+
+## Deep Reference Templates
+To ensure professional quality, you MUST use the appropriate template from `repo-docs/templates/`:
+- `repo-docs/templates/readme-template.md` — Standard project documentation template
+- `repo-docs/templates/product-readme-template.md` — Product archetype user-journey template
+- `repo-docs/templates/multi-skills-readme-template.md` — Large project with multiple skills/modules
+- `repo-docs/templates/single-skill-readme-template.md` — Single skill or focused utility documentation template
+- `repo-docs/templates/knowledge-readme-template.md` — Information-heavy/knowledge-base template
+- `repo-docs/templates/agents-template.md` — Standard agent onboarding instructions template
+- `repo-docs/templates/product-agents-template.md` — Agent instructions for product repositories
+- `repo-docs/templates/skills-agents-template.md` — Agent instructions for skills repositories
+- `repo-docs/templates/knowledge-agents-template.md` — Agent instructions for knowledge/research projects
+- `repo-docs/templates/manual-recon.md` — Methodology for manual repo scanning and classification