# Openplan Docs Init

> Initialize OpenPlan-style documentation generation before durable docs, memory, specs, or project knowledge are created. Use when Codex or Claude Code must bootstrap a docs repo, add OpenPlan-style docs to an existing repo, create initial doc maps/templates/needs snapshots/decision records, or prepare a project for document generation while preserving human goal/intent, dual-surface authority, AD…

- **Type:** Skill
- **Install:** `agentstack add skill-bananasjim-openplan-skill-openplan-docs-init`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BANANASJIM](https://agentstack.voostack.com/s/bananasjim)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BANANASJIM](https://github.com/BANANASJIM)
- **Source:** https://github.com/BANANASJIM/openplan-skill/tree/main/skills/openplan-docs-init
- **Website:** https://github.com/BANANASJIM/openplan-skill

## Install

```sh
agentstack add skill-bananasjim-openplan-skill-openplan-docs-init
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OpenPlan Docs Init

Use this after `$openplan-core` and usually after `$openplan-align` when a project needs an initial governed documentation surface before agents start generating durable docs.

## Core Principle

Document generation begins with authority and provenance, not with a pile of files. Generated docs must not present agent assumptions as human intent.

## When To Use

Use this skill when asked to:

- initialize an OpenPlan-style docs repo;
- add OpenPlan-style documentation governance to an existing code repo;
- create a minimal document map before generating project docs;
- seed needs snapshots, decision records, templates, or planning docs;
- prepare memory/docs for future Codex, Claude Code, or subagent sessions.

Do not use it for ordinary documentation edits after the document structure already exists. Use `$openplan-record` and `$openplan-garden` for that.

## Init Flow

1. Identify the target surface:
   - docs repo;
   - code repo;
   - single-repo project;
   - temporary teaching/reporting surface.
2. Identify the documentation root:
   - explicit user-provided path;
   - existing project convention;
   - `.openplan/` when docs should live inside a code repo without mixing with product docs;
   - `docs/` or repo root when that is the project convention;
   - a separate docs repo or absolute path when provided.
3. Identify authority sources:
   - explicit human goal/intent;
   - existing docs/design/ADR files;
   - code evidence;
   - prior handoff or needs snapshot;
   - agent inference.
4. Decide the minimum document map needed for the next phase.
5. Before creating durable docs, state:
   - docs root;
   - what will be generated;
   - which source backs each file;
   - what is inferred or pending confirmation;
   - whether the file is source of truth, draft, handoff, review, or disposable.
6. Generate only the smallest useful scaffold unless the user explicitly asks for a broader docs package.
7. Record an explicit human decision, or propose/request a decision record, when initialization creates or changes durable design/governance.
8. Seed a needs snapshot when the human goal/intent or project direction must survive across agents or sessions.
9. Run `$openplan-garden` after broad generation and `$openplan-record` for durable memory/docs updates.
10. Use `$openplan-research` first when the docs scaffold depends on facts not already backed by local durable context.

## Documentation Root

The docs root is configurable. Do not assume OpenPlan docs must live at the project root.

Valid docs roots include:

- `.openplan/` inside a code repo;
- `docs/` inside a project;
- the repository root for a dedicated docs repo;
- an absolute or relative path provided by the user;
- a separate docs repository.

All paths in the document map are relative to the selected docs root. For example, if the docs root is `.openplan/`, then `design/` means `.openplan/design/`.

Use the user's explicit docs root when provided. If no docs root is provided, discover existing conventions before proposing one. Do not move or rewrite existing docs into a new root unless the human explicitly requests migration.

## Minimal Document Map

Use project conventions first. If no convention exists, start from this map and prune aggressively. Paths are relative to the selected docs root.

| Path | Purpose | Durable |
|---|---|---|
| `README.md` or docs index | Entry point and navigation | yes |
| `design/` | Goal, principles, architecture, workflow | yes |
| `decisions/` | ADRs or decision records | yes |
| `planning/` | Roadmap, phases, open work | yes |
| `conventions/` | Naming, style, workflow rules | yes |
| `research/` | Evidence and investigations | medium-lived |
| `review/` | Review reports and findings | snapshot |
| `deviations/` | Accepted exceptions and rationale | durable until superseded |
| `_agent/state/needs-snapshot.md` | Cross-session intent snapshot | short/medium-lived |
| `_templates/` | Reusable document shapes | yes |

For a code repo, keep implementation specs and task artifacts separate from upstream design authority. For a docs repo, keep implementation notes out unless they explain documentation infrastructure.

## Generation Rules

- Do not copy OpenPlan internal docs into the target project as if they were project truth.
- Do not create many empty files to simulate maturity.
- Do not promote a draft into source of truth without explicit human confirmation.
- Mark assumptions as `Assumption`, `Inference`, or `Pending confirmation`.
- Prefer links and short summaries over duplicated rationale.
- If `design/` changes are introduced in an ADR-governed project, create or request a matching decision record.
- If docs and code disagree, report the conflict instead of choosing silently.
- If the generated docs affect future automation behavior, surface that as a human-owned decision.

## Stop Conditions

Stop and ask/report when:

- the human goal/intent is unclear;
- the target surface is ambiguous;
- the docs root is ambiguous and creating files would create competing sources of truth;
- generation would overwrite existing docs;
- the initial document map changes governance or architecture;
- a durable decision is needed but no human decision exists;
- the repo already has stronger local documentation governance and this skill would conflict with it.

Only the active human-facing coordinator asks the human. A delegated agent reports `Human decisions required` or `BLOCKED` with the missing decision.

## Output Contract

```markdown
Docs init mode:
Target surface:
Docs root:
Authority sources:
Generated/proposed paths:
Assumptions:
Human decisions required:
Follow-up skills:
Residual risk:
```

If editing is authorized, make the narrowest scaffold and report the changed paths.

## References

- `references/doc-map.md`: portable docs surface map.
- `references/init-contract.md`: initialization report and scaffold contract.
- `assets/claude-code-command.md`: Claude Code command/prompt seed.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BANANASJIM](https://github.com/BANANASJIM)
- **Source:** [BANANASJIM/openplan-skill](https://github.com/BANANASJIM/openplan-skill)
- **License:** MIT
- **Homepage:** https://github.com/BANANASJIM/openplan-skill

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-bananasjim-openplan-skill-openplan-docs-init
- Seller: https://agentstack.voostack.com/s/bananasjim
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.