Universal .docs/ template system and skills for AI coding agents. Generates project documentation, decision journals, review workflows, runs compliance refactoring, and onboards fresh agent sessions - with audit-before-code, disposition gates, anti-slop rules and a mandatory decision log baked in.
Works with any agent that reads files and runs commands: opencode, Claude Code, Cursor, Codex, Zed, and others (via skills or plain file copies).
# All bundled skills into your project (recommended)
npx skills add HullPerse/hp_docs
# bunx / pnpm equivalents
bunx skills add HullPerse/hp_docs
pnpm dlx skills add HullPerse/hp_docs
# Pick specific skills
npx skills add HullPerse/hp_docs --skill hp-docs
npx skills add HullPerse/hp_docs --skill deslop
npx skills add HullPerse/hp_docs --skill docs-refactor
npx skills add HullPerse/hp_docs --skill docs-onboard
npx skills add HullPerse/hp_docs --skill docs-init
npx skills add HullPerse/hp_docs --skill scandinavian-design
npx skills add HullPerse/hp_docs --skill test-architect
npx skills add HullPerse/hp_docs --skill test-reviewer
npx skills add HullPerse/hp_docs --skill security-audit
npx skills add HullPerse/hp_docs --skill project-documentation
# Pin a specific version (tag tree URL)
npx skills add https://github.com/HullPerse/hp_docs/tree/<tag>/skills/hp-docsManual install: copy skills/* into your project's .agents/skills/ and .docs/ next to your code.
Then open your agent in the project: it detects missing .docs/ placeholders and runs the first-run flow automatically.
No terminal needed: open any coding agent in a clean project and paste:
Install the hp_docs documentation package from github.com/HullPerse/hp_docs:
run the docs-init skill, or read its SKILL.md from the repo and follow it.
Ask me every question you need.
The docs-init skill handles everything end to end:
- Checks whether the package is already installed.
- Asks which runner to use (npx / bunx / pnpm dlx), installs into
.agents/skills/; falls back togit clone+ manual copy when no JS runtime exists; retries with--copyon Windows symlink failures. - Verifies all ten skills landed with readable frontmatter.
- Hands off to the first-run flow, which asks the seven initialization questions and generates
AGENTS.md+.docs/. - Reports what was created and how to update later (
npx skills update hp-docs).
The full package initializes through one skill install - templates travel inside the hp-docs skill itself (skills/hp-docs/templates/), so nothing else needs downloading.
cd <your-project>
npx skills add HullPerse/hp_docs # lands in .agents/skills/Then open any agent in the project. It finds AGENTS.md rules missing and runs the first-run flow automatically:
- Determines the project state (existing code / empty repo / fresh agent in a documented project).
- Lists available MCP tools.
- Scans package files, lockfile, directory tree.
- Asks seven questions: documentation language, package manager, lint preset, design preset, optional product spec, backend logging, security profile.
- Generates the full
.docs/from bundled templates with real project data. - Runs the docs health check and verifies lint/typecheck/test commands.
git clone https://github.com/HullPerse/hp_docs
cp -r hp_docs/skills/* <your-project>/.agents/skills/Same flow - the agent picks it up on the next session start.
<your-project>/
AGENTS.md # entry point for agents
product-spec.md # optional: feature source of truth
.docs/
AGENT_PROMPT.md # session contract
DEVELOPMENT.md # permanent conventions
TESTING.md # testing contract and migration flow
SECURITY.md # security contract: profile, capability budget, audit axes
DESIGN.md # chosen design preset
CHECKLIST.md # implementation checklist
REVIEWER.md # independent review prompt
DECISIONS.md # decision journal
ROADMAP.md # optional, 5+ features
agents-audit.prompt.md # rule freshness audit
features/ reviews/ answers/
Documentation language follows Question 1: English canonical by default; pick another language and the agent translates every file during initialization. examples/mini-project/ shows a filled example.
- Audit before code. Every task starts with analysis. Findings are classified Blocker / Risk / Gap / Optimization / Clear; a Blocker stops work until resolved by the user.
- Disposition gate. No new feature starts without two decisions: implementation disposition (now / defer / reject) and documentation destination (existing feature file / new one / DECISIONS.md only).
- Critical mode. The agent does not agree with bad ideas. A direct verdict comes with the reason, consequences, an alternative, and the condition that would change it. Sharp language about a decision is allowed; attacks on the person are not.
- Decision journal. Every significant decision lands in
.docs/DECISIONS.md(Decision / Context / Consequence / Source). Conflicts stop and ask; nothing is silently overridden. - Testing contract. Every testing axis is evaluated against behavior: unit, integration, edges, errors, regression, async/concurrency, performance, properties, mutation, fuzzing, coverage, mocks, flakiness, and maintenance. Existing suites migrate from a baseline.
- Security contract. Trust boundaries and a capability budget (every outbound channel declared and justified), full audit-axis review with static evidence, and exfiltration proof for published packages: no undeclared outbound channel. Security findings surface in every task, not only security ones.
(recommended)discipline. The marker appears only with real justification, never as filler.
- Anti-slop: ASCII punctuation only (no em/en dashes), no comment-parrots, no debug logs, no dead code, no placeholder data, no TODO instead of a logged decision.
- Deslop catalog (
deslopskill + DEVELOPMENT.md): EN/RU banned-word tags, structural tells (rule-of-three, parataxis, significance inflation, throat-clearing), voice preservation, draft -> audit -> final loop. - Ponytail ladder (mode full): YAGNI -> reuse project code -> stdlib -> native platform -> installed dependency -> one line -> minimal code. Bug fixes at the root via caller grep. Laziness is forbidden at trust boundaries, error handling against data loss, security, a11y.
- Grill mode: relentless one-question-at-a-time interviews for plans, each question with a recommended answer, depth-first through the decision tree.
- Stack-adaptive data flow: query-library projects get TanStack Query rules; desktop/CLI projects get background-task rules (UI never blocks); anything else gets equivalent rules agreed at init.
- Typing by language: TS (no
any, boundaryunknownnarrowed via Zod), Rust (Option/Result, isolatedunsafeFFI), Python (strict typing), Go (error values). - Design presets: Scandinavian (default: alpha ink ladder over white, Inter/system sans, 8px rhythm), neo-brutalism (radius 0, hard shadows), Zed dark (native tools). Custom style rewrites the preset section.
- Initialization questions: documentation language, package manager (Bun recommended), lint preset (Ultracite + oxlint/oxfmt recommended), design preset, optional product spec, backend logging, security profile.
- Mandatory MCP check at session start: agents list available servers and use them - docs tools (context7) for any library/API question before answering from memory, browser tools for UI verification.
| File | Purpose |
|---|---|
AGENTS.md |
Entry point: reading list, key rules, quick start |
.docs/AGENT_PROMPT.md |
Session contract: audit, questions, grill mode, ponytail ladder, response format |
.docs/DEVELOPMENT.md |
Permanent contract: conventions, typing by language, anti-slop + deslop catalog |
.docs/TESTING.md |
Behavior-first test strategy, migration, and verification contract |
.docs/SECURITY.md |
Security contract: profile, trust boundaries, capability budget, audit axes |
.docs/DESIGN.md |
Design presets and UI rules |
.docs/CHECKLIST.md |
Before/during/after implementation checklist |
.docs/REVIEWER.md |
Independent review prompt (read-only, evidence-based findings) |
.docs/DECISIONS.md |
Decision journal |
.docs/ROADMAP.md |
Optional phased feature roadmap |
.docs/answers/ |
Long research answers |
.docs/features/ |
Feature files (Idea / Comment / Pros / Cons) |
.docs/reviews/ |
Review issue files |
DOCUMENTATION_SPEC.md |
Optional completeness contract for product documentation |
product-spec.md |
Optional single source of truth for the feature set |
The core skill. On first run it analyzes the project stack, compares it against the canonical baseline, detects file naming conventions, and generates the complete .docs/ set from bundled templates. It owns the initialization questions (documentation language, package manager, lint preset, design preset, product spec, backend logging), performs deep code/dependency/architecture analysis with rule-compliance auditing on request, and runs docs health checks. Every later session works by the contract it generated.
A consolidated catalog of machine-writing tells merged from ten upstream anti-slop skills: banned-word lists for English and Russian, structural patterns (rule-of-three, parataxis, significance inflation, throat-clearing), punctuation limits, voice-preservation rules, and a draft -> audit -> final self-check loop. Use when drafting or reviewing any text that must not read as AI-generated.
The deep-dive design system behind the default DESIGN.md preset: black-and-white alpha ink ladder, restrained sans-serif typography, 8px rhythm, chapters-not-card-stacks layout, dark-theme recalculation rules, and contrast validation. Invoke for real UI redesign work; vendored verbatim from ericzakariasson/scandinavian-design.
Brings an existing codebase to compliance with its own .docs/ rules. Runs a compliance audit across file organization, naming, typing, data flow, state management, UI states, anti-slop and tests; reports a PASS/WARN/FAIL table; gets a disposition per work package (fix now / defer / reject); executes approved fixes with tests and re-verification.
Connects a fresh agent chat to a project that already has AGENTS.md and .docs/. Reads the entry point, follows its mandatory reading list, checks available MCP tools, and returns a compact contract summary (stack, hard rules, recent decisions) so the agent immediately works by project rules instead of guessing them.
Designs and writes tests across the full testing contract. Its modes cover unit, integration, edge cases, errors, regression, async/concurrency, performance, property, mutation, fuzzing, coverage, mocking, flakiness, and maintenance. It also migrates existing suites from a measured baseline.
Independently attacks tests for false positives, weak assertions, missing behavior and error paths, mock abuse, flaky timing, and unsupported coverage claims. It does not modify source code.
One skill covering the whole security surface as modes: dependency supply chain, secrets, injection, prototype pollution, path traversal, filesystem, process execution, SSRF, auth, input validation, logging, crypto, races, DoS, config, build, CI, git, privacy. Its centerpiece is the exfiltration proof for published npm packages and loggers: a static channel inventory where every outbound capability (network calls, child processes, lifecycle scripts, obfuscation markers, transitive dependencies) must resolve against the declared budget or become a finding.
Turns what a project already knows into user-facing documentation: reads .docs/ contracts, public API exports, tests, and benchmark result artifacts; builds a documentation map; generates pages against DOCUMENTATION_SPEC.md; validates that examples compile and links resolve; reports readiness percentage with named gaps. Numbers come only from recorded results - documentation is derived, never invented.
Installs the whole package into a clean project through an agent conversation: detects installation state, asks which runner to use (npx / bunx / pnpm dlx), handles no-node fallback via git clone and Windows symlink failures via --copy, verifies all ten skills landed, then hands off to the first-run flow which owns all initialization questions.
Canonical skill sources live in skills/; .agents/skills/ holds synced working copies. The package includes ten bundled skills, including test-architect, test-reviewer, security-audit, and project-documentation. Run scripts/sync-templates.ps1 (or .sh) after editing live files. Russian trigger phrases in some skill descriptions are kept deliberately as activation keys for Russian-speaking users; the deslop word-tag catalog is bilingual by design because it must catch Russian machine-text patterns too.
examples/mini-project/ shows filled docs on a fictional TypeScript/Bun CLI: what templates look like after first-run, including the decision to drop DESIGN.md and CHECKLIST.md as unnecessary for a non-UI micro-tool.## References
Built from real production usage and these upstream sources:
- Live examples: risovach (TypeScript web app), hpClean (Rust/GPUI desktop tool)
- Anti-slop lineage: anti-ai-slop-writing, soundshuman, elithrar/dotfiles anti-slop, stephenturner/skills deslop, humanizer-skill, slopkit, cursor/plugins unslop, blader/humanizer, no-ai-slop, stop-slop
- Design: scandinavian-design
- Interview format: mattpocock/skills grill-me
- Minimalism: ponytail (local skill)
- Tooling presets: ultracite, oxlint/oxfmt
- Skills distribution: vercel-labs/skills
.github/workflows/docs-check.yml verifies ASCII punctuation (vendor skill exempt), SKILL.md frontmatter integrity, and that skills/hp-docs/templates/ matches live files byte-for-byte.
scripts/pre-commit is a ready-to-use hook for consumer projects: dash check, explicit any, component naming.
Unlicense - public domain. Use, copy, modify, sell, whatever. No attribution required, no warranties given.