| name | project-wiki |
| description | Use this skill when the user explicitly wants to create, import, maintain, audit, or sync a docs-first project wiki for a software project. Covers agent guidance such as AGENTS.md or CLAUDE.md, wiki/Sources.md, wiki/plans/, wiki/log.md, source briefs, roadmap state, repo-local project-wiki-maintainer skills, and codebase-to-wiki reconciliation. Do not use for ordinary coding tasks unless the project already uses this wiki structure or the user asks to update project wiki context. |
Project Wiki
Use this skill to create and maintain a docs-first project memory layer for agentic development. Bootstrapping is one mode; ongoing feature planning, plan maintenance, codebase-to-wiki sync, decision capture, project-context logging, and wiki audits are also first-class work.
Core Workflow
- Detect the target project root and whether the request is setup, planning, codebase sync, maintenance, project-context logging, or audit work.
- Inspect before writing: root files, manifests, changed files, recent commits when relevant, existing agent guidance such as
AGENTS.md or CLAUDE.md, existing wiki/, source notes, PRDs, briefs, proposals, plans, roadmap, project-context log, workspace structure, and current Git state.
- Choose one mode:
bootstrap_new for a new docs-first project wiki, source index, local instructions, Git posture, and handoff.import_existing for preservation-first retrofit of an existing repo.plan_feature for creating a decision-complete plan before meaningful feature, architecture, config, schema, dependency, test, or app behavior work.update_plan for refining an existing plan after decisions, scope changes, implementation discoveries, or validation results.sync_changes for reconciling recent codebase changes, especially unplanned or partially planned changes, back into wiki/log.md, relevant plans, roadmap, source briefs, and source index.record_execution for appending durable project-context, validation, and decision history to wiki/log.md.audit_or_upgrade for checking or additively upgrading wiki artifacts, managed blocks, source indexes, plans, and local skill guidance.
- Load only the references required for the chosen mode.
- Create, update, or preserve wiki artifacts without overwriting user-authored files.
- Record material planning, validation, maintenance, bootstrap, or implementation changes in
wiki/log.md only when they affect durable project context, summarize unknowns, and leave clear next actions for the user's editor or terminal.
Reference Loading
Load references by mode instead of by default:
Use the repo-local skill guidance embedded in references/generated-baseline-artifacts.md only when repo-local skills are already in use or explicitly requested. If inspection reveals a conditional trigger mid-workflow, pause file creation, read the newly relevant reference, then continue with that context.
Project Root
This skill targets one project root. For monorepos or workspaces, identify whether the bootstrap applies to the repository root or a specific package/app root before writing. If the correct target root is ambiguous, stop and ask instead of creating root agent guidance or wiki/ in the wrong place.
Required Project Shape
Every completed bootstrap should create or preserve:
AGENTS.mdCLAUDE.md when the repository already uses Claude Code guidance or the user explicitly requests itwiki/AGENTS.mdwiki/index.mdwiki/log.mdwiki/Sources.mdwiki/plans/README.mdwiki/roadmap.md- repo-local
.agents/skills/project-wiki-maintainer/SKILL.md when repo-local skills are already in use or explicitly requested
Generate source briefs only when the project evidence justifies them:
wiki/sources/prd.md when product intent, audience, user journey, feature scope, constraints, or non-goals need durable preservation.wiki/sources/technical-brief.md when implementation choices, architecture, stack defaults, integrations, runtime boundaries, testing posture, or handoff risks need durable preservation.wiki/sources/marketing-brief.md when the project has a real public-entry, launch, signup, download, acquisition, or external-audience need.wiki/sources/design-brief.md when the project has a meaningful UI, frontend, website, dashboard, visual workflow, design system, or interaction-heavy product surface.wiki/Architecture.md when durable cross-cutting architecture decisions, system boundaries, data flow, integration surfaces, or runtime constraints need preservation.
Always create wiki/plans/README.md. During import_existing, classify lifecycle before creating deeper plan structure. Treat existing live products, internal tools in active use, libraries, archives, maintenance-mode projects, and unknown lifecycle as post-MVP unless source evidence or the user explicitly says the project is pre-launch, greenfield, or building an MVP. Do not create wiki/plans/mvp/ by default for imported or existing live projects; use wiki/roadmap.md, wiki/plans/features/, wiki/plans/maintenance/, or wiki/plans/releases/ only when concrete workstreams justify them. Create wiki/plans/mvp/ only when the project clearly needs multiple ordered implementation sessions for greenfield, pre-launch, or explicitly MVP work. If unsure, do not create wiki/plans/mvp/; record it as a next planning decision. When using mvp/, prefer a small number of stages with multiple related units in each. Do not create many single-unit stages unless each has a real phase gate, external dependency, or distinct outcome boundary.
Resume And Continue Guard
When the user asks to "resume", "continue", "pick up", "look at", or "work on" a plan, branch, worktree, or feature, do not assume permission to create plans or edit code.
First orient:
- inspect current branch, worktree, Git status, and changed files
- inspect
wiki/plans/README.md and the closest relevant plans
- summarize current plan state, current unit, blockers, and ambiguity
- if no active plan exists, say that clearly
- ask whether the user wants to create a plan, revise a plan, or begin implementation
Do not create a new plan, infer design direction, or edit code until the user chooses the next action, unless the user explicitly requested planning or implementation. A branch or worktree name is not enough source context to decide scope.
Feature Planning
Before meaningful code, config, schema, dependency, architecture, test, build, or app behavior changes in a project that uses this wiki structure, find the closest relevant plan under wiki/plans/. If none exists, create a decision-complete plan before implementation unless the user explicitly asked for exploratory analysis only.
Fast-path exception: for small, local, reversible fixes that do not change product behavior, architecture, schema, dependencies, build configuration, public APIs, security posture, or durable project direction, do not create a plan. Make the change, validate it, and avoid wiki/log updates unless the fix reveals durable project knowledge.
Before creating a feature plan, inspect repo, wiki, and source context first, then aim for maximum useful clarification. Ask questions whenever answers would improve scope, non-goals, architecture, schema, UX, dependencies, validation, rollout, risks, sequencing, or the next execution unit. Prefer a focused batch of 3-7 high-leverage questions, grouped by theme when useful. Do not proceed directly to a plan unless the user asked to skip questions, the plan is a small fast-path fix, or the repo/wiki/source evidence already answers the important planning questions. If a remaining unknown is minor or can be handled safely, proceed and record the assumption in the plan.
Choose the planning shape before writing plan files. Depending on scope, propose one of: a compact feature plan with one execution unit, a single stage with multiple units, multiple stages with multiple units per stage, or no durable plan for fast-path work. Do not default to mvp/ stages when a feature plan or single-stage unit list is clearer.
Optimize plans for CLI use. The first screen of wiki/plans/README.md and every active plan should show status, planning shape, current unit, blockers, next action, and useful read commands. When orienting or handing off, summarize the current plan state instead of dumping long markdown, and provide exact paths or sed -n commands for deeper reading.
For concrete plan/no-plan cases, use the Planning Examples in references/planning-contract.md.
For frontend, UI, website, dashboard, or interaction-heavy work, inspect wiki/sources/design-brief.md when present before planning or implementation. If no design brief exists but repository evidence or source context contains durable UI design decisions, create or update the design brief before executing substantial UI work.
Plans should define intent, scope, non-goals, dependencies, validation, and the next execution unit. Every execution unit must include a ## Verification section with automated, manual, or explicitly deferred verification. Do not mark a unit complete unless verification is recorded or deferred with a reason. Update an existing plan when corrective work or implementation discoveries change the intended path. Move fully complete plans into wiki/plans/zzz_completed/ after the top-level plan, all stages, all units, completion gates, and verification records support completion; remove archived plans from active current-plan slots while preserving compact archive links. Create a new plan only when the work introduces a new durable feature track.
Keep routine implementation history in Git, not in plans or wiki/log.md. Append wiki/log.md only for material planning, validation, implementation, or maintenance work that changes durable project context, and link the entry back to the relevant plan or unit when one exists.
Codebase Sync
When changes were made before a plan existed or when the wiki may be stale, reconcile from repository evidence before writing. Inspect Git status, changed files, relevant diffs, recent commits, tests or validation output when available, and the current wiki state.
Use wiki/log.md as the primary sync artifact for context changes, not as a duplicate commit history. Update existing plans only when the changes completed, invalidated, narrowed, expanded, or redirected planned work. Create a retrospective feature plan only when the changes introduced a durable feature track or future implementation dependency that needs a maintained plan.
Log Policy
Git history owns routine implementation history. wiki/log.md owns durable project-context history: bootstrap/import events, planning direction changes, codebase sync summaries after unplanned work, validation results that affect plans or roadmap, source-context changes, and important decisions discovered during implementation.
Before appending to wiki/log.md, ask: would this entry help a future agent make a better project decision? If not, do not log it.
Do not add log entries for routine commits, every code edit, every test run, formatting, minor refactors, or implementation details already obvious from Git. Prefer one log entry per meaningful project-context change, not one per commit.
Do not log routine notes such as "ran npm test", "fixed lint error", "updated import", "changed CSS class", or "committed changes" unless the result changes project direction, validation status, public behavior, or future planning.
Keep wiki/log.md scan-friendly. If it becomes hard to scan, summarize older entries into wiki/log-archive.md or a dated archive such as wiki/log/2026.md, then leave a short pointer from the current log to the archive. Do not rewrite recent decision history unless the user explicitly asks for log cleanup.
Update wiki/roadmap.md, wiki/Sources.md, source briefs, or wiki/index.md only when the codebase changes reveal durable project knowledge, source evidence, architecture, product behavior, UI design direction, or next-step changes. Name unknowns when the reason or intent behind a change cannot be inferred from the repository and user context.
Safety Rules
- Never overwrite existing project files or repo-local skill files.
- Use bounded managed blocks only when updating existing agent guidance.
- Follow existing agent guidance conventions. If the repo already uses
CLAUDE.md, preserve and update that file with a managed block when appropriate; do not create extra agent-specific files unless the convention already exists or the user asks.
- Initialize Git for newly created projects unless the user opts out.
- Preserve existing Git history for imported repos.
- Do not commit, push, install dependencies, or generate scaffold code by default. Follow the repo automation policy when it explicitly allows commits or other actions.
- Do not create implementation plans in root-level
docs/, tasks/, or ad hoc planning files outside wiki/.
- Never leave bracketed placeholders in generated project files. Replace them with project-specific content, or write
Unknown when current evidence does not support a value.
- Name unknowns and contradictions instead of inventing certainty.
- Keep maintained project knowledge under
wiki/; do not create root-level docs/ or tasks/ for durable planning.
Repo Automation Policy
Use a repo-level automation policy to remember how much autonomy the user wants. Store it in wiki/AGENTS.md and, when useful, summarize or point to it from root AGENTS.md or CLAUDE.md.
Default policy when none exists:
- Commit docs-only wiki changes: ask
- Commit code changes: ask
- Push changes: ask
- Install dependencies: ask
- Run long commands: ask
- Create plans before code: meaningful-only
During bootstrap, import, or audit, ask whether the user wants to keep the conservative default or allow more automation for that repo. Good common setting: Commit docs-only wiki changes: auto, while keeping code commits, pushes, and dependency installs as ask.
When auto-committing is allowed:
- inspect
git status --short before committing
- include only intended files for the completed task
- for docs-only wiki commits, stage only
wiki/, root agent guidance files, and other docs files intentionally changed by project-wiki work
- leave unrelated dirty files untouched and mention them
- do not commit code changes unless the policy explicitly allows code commits and required verification is recorded
- do not push unless the policy explicitly allows auto-push or the user requests it
- use concise messages such as
Initialize project wiki, Update project wiki, Sync project wiki with recent changes, or Add feature plan
Source Context
wiki/Sources.md is always required as the human source index. It should catalog source material, repository evidence, prompts, notes, briefs, proposals, and unknowns without inventing certainty.
When source briefs are useful, wiki/sources/prd.md owns product intent and user journey. wiki/sources/technical-brief.md translates that intent into executable technical defaults and implementation surfaces without overriding the PRD. If public-facing acquisition, signup, download, or launch flow matters, add a compact wiki/sources/marketing-brief.md. If the project has a durable UI or visual interaction surface, wiki/sources/design-brief.md owns interface principles, visual system direction, interaction patterns, responsive expectations, accessibility expectations, design validation, and known design unknowns.
Every source brief should include a ## Status section with Last reviewed, Evidence basis, and Confidence: high|medium|low. During sync_changes, if implementation or new user direction contradicts a source brief, update the brief status, lower confidence, or record the contradiction instead of treating the brief as authoritative.
If source docs contradict repo evidence or each other on scaffold-impacting choices, stop short of scaffold handoff recommendations and ask for clarification.
Scaffold Boundary
App scaffold generation is not a core mode of this skill. If the user explicitly asks for scaffold code after bootstrap or import, treat it as a separate implementation task: use repo conventions, source docs, and the relevant stack-specific workflow, and keep wiki/log.md, plans, source briefs, and roadmap state updated when the scaffold changes durable project knowledge.
Do not choose a stack from thin context, install dependencies, or generate app files as part of ordinary project-wiki bootstrap, import, planning, sync, or audit work.
Handoff
End with a concise summary of created, updated, preserved, skipped, failed, blocked, and present-but-not-upgraded artifacts; Git result; unresolved unknowns; and next actions. Include the reason and safest next action for every non-success result. Prefer editor, folder, terminal, and key-file handoffs over keeping the user inside a custom app surface.
Maintaining This Skill
Keep this skill concise and move detailed reusable guidance into references/. Keep README.md focused on public GitHub distribution. Do not overwrite user-authored files when testing the bootstrap workflow against another repo.
References
