# project-governance-docs

Adopt this skill: https://proskills.md/skills/other/wnjnrwinston-project-governance-docs-source-project-governance-docs

Page: https://proskills.md/skills/other/wnjnrwinston-project-governance-docs-source-project-governance-docs
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: source/project-governance-docs/SKILL.md
size: 8010
upstream: https://github.com/wnjnrwinston/project-governance-docs/blob/main/source/project-governance-docs/SKILL.md

```text
---
name: project-governance-docs
description: Create project planning, governance, execution docs, or AI-maintained brain docs for either a new project or an existing codebase. Use when a user asks to define a project before coding, create brief/spec/architecture/runbook/tasks/decisions docs, retrofit governance onto a project already in progress, document current state first, create or maintain an Infinite Brain/brain-map/atomic nodes system, prevent fresh-session dumb zone, or keep AI-readable project memory across sessions. Especially use for project foundation, v1 scope, acceptance criteria, engineering rules, guardrails, phased tasks, risks, assumptions, open questions, AI-maintained knowledge graphs, and Obsidian-compatible Markdown brain docs. Also trigger on workflow selector phrases and aliases including `docs menu`, `/docsmenu`, `updatedocs`, `update impacted docs`, `greenfield`, `retrofit`, `brain`, `infinite brain`, `brain-first`, `backup project`, and `restore project`.
---

# Project Governance Docs

Create the smallest useful governance/doc pack for the user's actual project state.

Default goal:
- define or document the project clearly
- control scope
- avoid invented architecture
- separate facts from assumptions
- make the next implementation steps obvious

## Quick invoke

If the user says `docs menu` or `/docsmenu`, always present the fixed Docs Menu below verbatim.
Do not improvise a custom menu.
Do not summarize it.
Do not replace it with repo-specific shortcuts.
Treat `updatedocs` as a direct alias for `update impacted docs`.
Treat `greenfield`, `retrofit`, `brain`, `infinite brain`, `brain-first`, `backup project`, and `restore project` as direct workflow selections even when the user sends only that one word.
If the workflow choice is already explicit, continue directly instead of showing the menu again.
If memory is fuzzy or context is long, prefer re-reading this skill over improvising the docs-menu behavior.

## Docs Menu
Choose one:

1. `greenfield` — define the project before coding
   - default docs: `docs/PROJECT_BRIEF.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md`, `docs/ENGINEERING_RULES.md`, `docs/GUARDRAILS.md`, `docs/RUNBOOK.md`, `docs/TASKS.md`, `docs/DECISIONS.md`
2. `retrofit` — document and govern the current implementation first
   - default docs: `docs/CURRENT_STATE.md`, `docs/SPEC.md`, `docs/ENGINEERING_RULES.md`, `docs/GUARDRAILS.md`, `docs/RUNBOOK.md`, `docs/TASKS.md`
3. `update impacted docs` — update only the documentation affected by the latest change
   - update only the docs that became inaccurate
4. `backup project` — create a real project checkpoint before risky changes
   - do not create governance docs by default
   - if the target project/repo is unclear, ask which one should be backed up
5. `restore project` — restore from the latest real checkpoint or backup
   - do not claim restore is possible unless a real checkpoint exists
   - if the target project/repo is unclear, ask which one should be restored

6. `brain` - create or maintain an AI-first Infinite Brain
   - default docs: `docs/brain/brain-map.md`, `docs/brain/project-state.md`, and atomic nodes under `docs/brain/nodes/`
   - use this when the user wants fresh sessions to continue from concise AI-readable project memory

Reply with one option name to continue.

Treat `docs menu` and `/docsmenu` as workflow selectors, not as literal system commands.

## Workflow decision

First decide which mode applies.

### Mode 1: Greenfield foundation
Use this when:
- the user says the project has not started yet
- there is no meaningful implementation yet
- the user wants planning before coding
- the user asks for project brief/spec/architecture/decisions first
- the user selects `greenfield` from `docs menu`

Then read:
- `references/greenfield-mode.md`
- `references/doc-templates.md`

### Mode 2: Retrofit governance
Use this when:
- the user says the project is already in progress
- code already exists and should be inspected first
- the user wants current-state docs, governance, rules, runbook, or tasks based on observed reality
- the user explicitly says not to restart or redesign the project
- the user selects `retrofit` from `docs menu`

Then read:
- `references/retrofit-mode.md`
- `references/doc-templates.md`

### Mode 3: Brain-first governance
Use this when:
- the user wants Codex/AI to maintain project memory instead of the user reading long canonical docs
- the user wants to prevent fresh-session dumb zone
- the user asks for Infinite Brain, brain-map, atomic nodes, Obsidian-compatible brain docs, or AI-first documentation
- the user selects `brain`, `infinite brain`, or `brain-first` from `docs menu`

Then read:
- `references/brain-first-mode.md`
- `references/doc-templates.md`

If classification is ambiguous, inspect the workspace first and state the uncertainty explicitly.

## Core rules

Always:
- document current reality first when code exists
- distinguish confirmed facts from assumptions
- distinguish must-have / in-scope from nice-to-have / deferred
- keep v1 minimal and buildable
- identify critical risks separately from cosmetic issues
- prefer practical execution over elegant overdesign
- update only the docs actually affected by the change
- prefer a real checkpoint or rollback path before risky implementation work
- when brain docs exist, treat `docs/brain/brain-map.md` as the first fresh-session entrypoint and keep impacted brain nodes current

Never:
- invent architecture that is not justified by the project state
- broaden a narrow task into a general system redesign
- hide unknowns; mark them clearly
- treat assumptions as decisions already locked
- rewrite the entire doc set when only one or two docs changed
- claim rollback or undo exists unless it is real for that project

## Documentation maintenance rule

After a task:
- update only the impacted docs
- do not rewrite unrelated docs
- if implementation changed but existing docs are still accurate, leave them alone
- if no behavior, scope, rule, operation, or task status changed, no doc update is required
- prefer targeted edits over broad doc refreshes
- if `docs/brain/` exists, update impacted brain nodes after meaningful code, scope, decision, pattern, lesson, risk, or task changes
- do not ask the user to maintain brain docs manually; Codex owns documentation hygiene unless the user says otherwise

## Brain-first fresh-session rule

When a project has `docs/brain/brain-map.md`:
- read `docs/brain/brain-map.md` before broad documentation or implementation work
- read `docs/brain/project-state.md` if it exists
- follow the links to only the relevant nodes for the current task
- if brain docs and code disagree, inspect code before trusting either
- if brain docs and older linear docs disagree, mark the conflict and prefer observed code or explicit user direction
- after meaningful work, update only impacted brain nodes and `brain-map.md`
- create new nodes only for durable facts, decisions, patterns, lessons, tasks, or risks that will likely matter in a future session

Use brain docs to reduce context load, not to create a large passive archive.

## Lean learning-loop upgrades

Use these upgrades only when they materially improve execution quality.
Keep them small, operational, and tied to repo reality.

### 1. Lesson extraction
When a mistake, near-miss, repeated confusion, or verification gap appears, compress it into a small reusable lesson.

Preferred format:
- incident
- cause
- prevention rule
- applies to
- permanence level

Permanence levels:
- `temporary` = useful for the next few tasks only
- `project-specific` = should stay with this repo/workflow
- `durable principle` = reusable across projects unless contradicted

Only promote a lesson when it helps avoid repeat failure.
Do not create a large lesson log by default.

### 2. Failure fallback behavior
When lint/build/env/api/tooling inspection becomes unclear or fails:
- stop broad implementation work
- sep
```

## File: README.md
upstream: https://github.com/wnjnrwinston/project-governance-docs/blob/main/README.md

````text
# Project Governance Docs

A small OpenClaw skill for practical project governance workflows:

- **greenfield** - define the project before coding
- **retrofit** - document and govern the current implementation first
- **brain** - maintain an AI-readable Infinite Brain for fresh-session continuity

It also supports a simple workflow selector:

- `docs menu`
- `/docsmenu`
- `updatedocs`
- `greenfield`
- `retrofit`
- `brain`
- `infinite brain`
- `brain-first`
- `update impacted docs`
- `backup project`
- `restore project`

## What It Does

This skill helps keep project work practical and controlled by:

- defining foundation docs before implementation when a project is new
- documenting current reality first when a project already exists
- creating and maintaining concise brain docs for AI fresh sessions
- separating facts from assumptions
- keeping v1 scope minimal
- avoiding unnecessary redesign
- updating only impacted docs instead of refreshing everything
- reading `docs/brain/brain-map.md` first when brain docs exist
- using real backup/restore discipline instead of fake undo
- extracting compact lessons from repeated mistakes or ambiguity
- preferring bounded fallback behavior when tooling/build/lint/env inspection becomes unclear
- requiring compact proof of completion instead of weak "done" claims

## Modes

### Greenfield

Use when the project has not started yet and you want foundation docs before coding.

Default docs created:

- `docs/PROJECT_BRIEF.md`
- `docs/SPEC.md`
- `docs/ARCHITECTURE.md`
- `docs/ENGINEERING_RULES.md`
- `docs/GUARDRAILS.md`
- `docs/RUNBOOK.md`
- `docs/TASKS.md`
- `docs/DECISIONS.md`

### Retrofit

Use when the project already exists and you want docs/governance based on the current implementation first.

Default docs created:

- `docs/CURRENT_STATE.md`
- `docs/SPEC.md`
- `docs/ENGINEERING_RULES.md`
- `docs/GUARDRAILS.md`
- `docs/RUNBOOK.md`
- `docs/TASKS.md`

### Brain

Use when you want Codex/AI to maintain a compact project memory layer that a fresh session can read first.

Default docs created:

- `docs/brain/brain-map.md`
- `docs/brain/project-state.md`
- `docs/brain/nodes/facts/`
- `docs/brain/nodes/decisions/`
- `docs/brain/nodes/patterns/`
- `docs/brain/nodes/lessons/`
- `docs/brain/nodes/tasks/`
- `docs/brain/nodes/risks/`

Expected behavior:

- read `docs/brain/brain-map.md` before broad planning or implementation work
- open only the linked nodes relevant to the current task
- update only impacted brain nodes after meaningful work
- keep Obsidian optional; Markdown and Git remain enough

### Update Impacted Docs

Use after a completed change when only some docs became inaccurate.

Expected behavior:

- update only the docs affected by the latest change
- leave unrelated docs untouched if they are still accurate

### Backup Project

Use before risky or multi-file changes.

Expected behavior:

- create a real checkpoint for the current clearly scoped project
- if project scope is unclear, ask which project/repo should be backed up
- prefer git if available
- otherwise create a manual backup

### Restore Project

Use when you need to recover to a real checkpoint.

Expected behavior:

- restore the current clearly scoped project from a real backup/checkpoint if available
- if project scope is unclear, ask which project/repo should be restored
- say so clearly if no real restore path exists

## Quick Invoke

If you say `docs menu` or `/docsmenu`, the skill should present the fixed menu verbatim and should not improvise a custom version:

1. `greenfield`
2. `retrofit`
3. `update impacted docs`
4. `backup project`
5. `restore project`
6. `brain`

Additional selector behavior:

- `updatedocs` = alias for `update impacted docs`
- `greenfield`, `retrofit`, `brain`, `infinite brain`, `brain-first`, `backup project`, and `restore project` can be sent by themselves as direct workflow selections
- if the workflow choice is already explicit, continue directly instead of showing the menu again
- if `/docsmenu` appears after a long conversation, prefer the fixed menu behavior over remembered custom menus

## Lean Learning-Loop Features

These upgrades are intentionally small and integrated into the existing workflows.

Included behavior covers:

- lesson extraction
- failure fallback behavior
- done + evidence discipline
- post-task review / teach-back
- light pre-mortem thinking
- skill-candidate judgement
- knowledge promotion lifecycle (`capture -> compress -> evaluate -> promote -> retain -> retire`)

## Included Files

```text
index.html
styles.css
source/project-governance-docs/
  SKILL.md
  references/
    brain-first-mode.md
    decision-rules.md
    doc-templates.md
    greenfield-mode.md
    retrofit-mode.md

dist/project-governance-docs.skill
```

## Installation

### Option 1 - Packaged Skill

Download:

- `dist/project-governance-docs.skill`

Then install/import it using your OpenClaw skill import workflow.

### Option 2 - Manual Source Install

Copy the skill folder from:

- `source/project-governance-docs/`

into your local OpenClaw skills directory, then reload/restart OpenClaw if needed.

## First Use

After install, try:

```text
/docsmenu
```

That should present:

- `greenfield`
- `retrofit`
- `update impacted docs`
- `backup project`
- `restore project`
- `brain`

## Usage Examples

### Show Menu

```text
/docsmenu
```

### New Project

```text
greenfield - before coding, define the project first. Create the foundation docs and keep v1 minimal.
```

### Existing Project

```text
retrofit - check current state first, then make the docs based on the existing implementation. Do not redesign it.
```

### Fresh-Session Brain

```text
brain - setup docs/brain/brain-map.md, project-state.md, and a small set of atomic nodes so a new AI session can continue without replaying the whole chat.
```

### After A Change

```text
update impacted docs - update only the docs affected by the latest confirmed change in the current project context.
```

### Before Risky Work

```text
backup project - create a real checkpoint for the current clearly scoped project; if the target project is unclear, ask which project/repo should be backed up first.
```

### Recover From Checkpoint

```text
restore project - restore the current clearly scoped project from a real checkpoint; if the target project is unclear, ask which project/repo should be restored first.
```

## Contributing

Contributions are welcome. Keep changes small, practical, well-scoped, and aligned with the current workflow philosophy.

## License

MIT
````
