# Plannotator

> Plannotator product and open-source documentation, planning templates, framework profiles, comparisons, and guides to AI-assisted development.

## Docs

- [Plannotator Documentation and Learning](https://docs.plannotator.ai/index.md): Choose open-source Plannotator documentation, Workspaces, automation guides, planning templates, framework profiles, comparisons, or practical AI-development guides.
- [Plannotator Art Gallery](https://docs.plannotator.ai/gallery.md): Browse Plannotator illustrations for AI coding plans, agent instructions, review artifacts, revision diffs, and living documentation workflows.
- [Plannotator OSS Documentation](https://docs.plannotator.ai/open-source/index.md): Install Plannotator, annotate plans and documents, review code changes, and return feedback to your coding agent.
- [Install Plannotator](https://docs.plannotator.ai/open-source/start/installation.md): Install, update, or remove Plannotator on macOS, Linux, WSL, or Windows, then finish setup for your coding agent.
- [Plannotator Open Source Security](https://docs.plannotator.ai/open-source/security.md): How Plannotator OSS keeps review data local, protects release artifacts, runs automated security checks, and accepts private vulnerability reports.
- [Self-Host Plannotator's Deprecated Share Services](https://docs.plannotator.ai/open-source/self-hosting.md): Deploy the deprecated OSS share portal and encrypted paste service for compatibility with asynchronous Plannotator share links.
- [Review Plannotator Sessions over Tailscale](https://docs.plannotator.ai/open-source/tailscale.md): Open Plannotator review and annotation sessions from another device through Tailscale Serve without binding the server beyond localhost.
- [Open Plannotator on Another Device](https://docs.plannotator.ai/open-source/remote-access.md): Open a Plannotator session from a phone, tablet, local browser, or another computer through Tailscale, a trusted private network, SSH, or a development-container port forward.
- [Install and Manage Plannotator Skills](https://docs.plannotator.ai/open-source/start/skills.md): Install Plannotator's core or extra agent skills, choose specific skills and hosts, update them, and remove them.
- [Annotate Your First Plan](https://docs.plannotator.ai/open-source/start/quickstart.md): Annotate a Markdown plan, then open a folder to browse and annotate plans, specs, ADRs, and notes in one Plannotator session.
- [Review Your First Code Change](https://docs.plannotator.ai/open-source/start/code-review-quickstart.md): Open a local code diff in Plannotator, comment on changed lines, and send clear feedback to your coding agent.
- [Open Plannotator](https://docs.plannotator.ai/open-source/start/open-plannotator.md): Start Plannotator from a supported coding agent or run it directly from the command line.
- [Turn Plannotator Feedback into Agent Skills](https://docs.plannotator.ai/open-source/start/compound-value.md): Use feedback from plan reviews, document annotations, and code reviews to create agent skills that match your preferences.
- [Review an AI Coding Plan with Plannotator](https://docs.plannotator.ai/open-source/workflows/plan-review.md): Annotate an AI coding plan, send exact feedback to the agent, approve it, and compare the next revision.
- [Open and Annotate Markdown, Documents, URLs, and Folders](https://docs.plannotator.ai/open-source/workflows/documents.md): Open a Markdown file, plain-text data file, web page, HTML file, or folder in Plannotator, then annotate it or send edits back to your agent.
- [Annotate a Folder with Plannotator](https://docs.plannotator.ai/open-source/workflows/folders.md): Open a folder of supported documents, plain-text config and data files, and HTML in one Plannotator session.
- [Annotate HTML in Plannotator](https://docs.plannotator.ai/open-source/workflows/html.md): Render a local HTML file in Plannotator, annotate text or elements, compare versions, and share an encrypted portable copy.
- [Add Annotations and Send Feedback](https://docs.plannotator.ai/open-source/workflows/annotations-and-feedback.md): Comment on exact text, add a global comment, draw on image attachments, and choose whether to request changes, approve, or dismiss a review.
- [Use Local Version History and Plan Diffs](https://docs.plannotator.ai/open-source/workflows/version-history.md): Compare plan and document revisions in Plannotator and control the local history copies stored on your machine.
- [Share a Plannotator Session](https://docs.plannotator.ai/open-source/workflows/sharing.md): How the deprecated OSS sharing flow, retained for compatibility, uses URL fragments or encrypted short-link uploads and imports returned annotations.
- [Code Review with Plannotator](https://docs.plannotator.ai/code-review/index.md): Review local changes, GitHub pull requests, and GitLab merge requests with open-source Plannotator, then return precise feedback to coding agents.
- [Review local code changes](https://docs.plannotator.ai/open-source/workflows/local-changes.md): Open a browser review for local Git, GitButler, Jujutsu, or Perforce changes and send line-specific feedback to your coding agent.
- [Review GitButler Workspaces, Stacks, and Branches](https://docs.plannotator.ai/open-source/workflows/gitbutler.md): Review a GitButler workspace, stacked branches, or one branch layer in Plannotator, with exact detection rules, limits, and troubleshooting.
- [Review pull requests and merge requests](https://docs.plannotator.ai/open-source/workflows/pull-requests.md): Review GitHub pull requests or GitLab merge requests locally, then send feedback to your agent or post it to the provider.
- [Ask AI during a review](https://docs.plannotator.ai/open-source/workflows/ask-ai.md): Ask a configured local AI provider about selected diff lines while keeping its answers separate from submitted review feedback.
- [Run Agent Reviews, Code Tours, and Guided Reviews](https://docs.plannotator.ai/open-source/workflows/agent-reviews.md): Run a code review, Code Tour, Guided Review, or custom review skill with an installed local agent CLI and understand its provider guardrails.
- [Automate and Customize Plannotator](https://docs.plannotator.ai/open-source/reference/index.md): Connect Plannotator to coding agents, customize feedback, run it from hooks, and add annotations from scripts and other tools.
- [Plannotator CLI reference](https://docs.plannotator.ai/open-source/reference/cli.md): Commands and flags for reviewing changes, annotating files and URLs, reopening sessions, and reading saved plan decisions.
- [Configure Plannotator](https://docs.plannotator.ai/open-source/reference/configuration.md): How Plannotator combines command flags, environment variables, config.json, and browser UI settings.
- [Plannotator environment variables](https://docs.plannotator.ai/open-source/reference/environment-variables.md): Runtime, browser, remote-session, sharing, installer, and agent environment variables supported by Plannotator.
- [Plannotator OSS Privacy and Data Flow](https://docs.plannotator.ai/open-source/reference/privacy-and-data-flow.md): What Plannotator OSS keeps locally, which automatic and optional network requests it makes, and how sharing and hosted products change the data boundary.
- [Customize Feedback](https://docs.plannotator.ai/open-source/reference/custom-feedback.md): Change the messages Plannotator returns after plan, document, and code-review decisions.
- [Plannotator keyboard shortcuts](https://docs.plannotator.ai/open-source/reference/keyboard-shortcuts.md): Keyboard shortcuts for plan review, document annotation, code review, images, search, and AI panels.
- [Use Plannotator Approval Gates and Automation Hooks](https://docs.plannotator.ai/open-source/reference/hooks.md): Gate a document or agent message, distinguish approval from dismissal, and return plain text, structured JSON, or hook-native output.
- [Plannotator Local Server and API](https://docs.plannotator.ai/open-source/reference/local-api.md): Security, remote binding, session lifetime, and HTTP routes for Plannotator plan, document annotation, and code review servers.
- [Add external annotations to Plannotator](https://docs.plannotator.ai/open-source/reference/external-annotations.md): Tested HTTP schemas for adding tool findings to a live Plannotator plan, document, or code review session.
- [Choose Your Agent](https://docs.plannotator.ai/open-source/agents/index.md): Choose a supported coding agent, editor, or note app and follow its Plannotator setup guide.
- [Use Plannotator with Claude Code](https://docs.plannotator.ai/open-source/agents/claude-code.md): Install Plannotator for Claude Code, review plans at ExitPlanMode, and invoke document and code review skills.
- [Use Plannotator with Codex](https://docs.plannotator.ai/open-source/agents/codex.md): Enable Plannotator's Codex Stop hook, review plans after they render, and invoke review skills or shell commands.
- [Use Plannotator with OpenCode](https://docs.plannotator.ai/open-source/agents/opencode.md): Add the Plannotator OpenCode plugin, choose its planning workflow, and install manual review commands.
- [Use Plannotator with Copilot CLI](https://docs.plannotator.ai/open-source/agents/copilot-cli.md): Install Plannotator's Copilot CLI plugin for plan interception, code review, and document annotation.
- [Use Plannotator with Gemini CLI](https://docs.plannotator.ai/open-source/agents/gemini-cli.md): Configure Gemini CLI plan review and install Plannotator's review and annotation commands.
- [Use Plannotator with Pi](https://docs.plannotator.ai/open-source/agents/pi.md): Install the Plannotator Pi extension and use plan mode, code review, document annotation, and last-message review.
- [Use Plannotator with Amp](https://docs.plannotator.ai/open-source/agents/amp.md): Install Plannotator's Amp plugin and run manual code, file, and last-answer reviews from the command palette.
- [Use Plannotator with Droid](https://docs.plannotator.ai/open-source/agents/droid.md): Install Plannotator's Droid plugin for manual code review, file annotation, and last-message review.
- [Use Plannotator with Kiro CLI](https://docs.plannotator.ai/open-source/agents/kiro-cli.md): Install Plannotator's Kiro CLI skills and example custom agent for manual document and code review.
- [Open Plannotator in VS Code](https://docs.plannotator.ai/open-source/agents/vscode.md): Open Plannotator plan and code reviews in VS Code tabs and add editor selections to the active review.
- [Open review files in Zed](https://docs.plannotator.ai/open-source/agents/zed.md): Open the current local Plannotator review file in Zed or Zed Preview.
- [Save Plannotator Plans to Obsidian or Bear](https://docs.plannotator.ai/open-source/agents/notes.md): Configure Plannotator to save plans to an Obsidian vault or Bear notes.
- [Save Plannotator Plans to Octarine](https://docs.plannotator.ai/open-source/agents/octarine.md): Configure Plannotator to save plans to a named Octarine workspace and folder.
- [Troubleshoot Plannotator](https://docs.plannotator.ai/open-source/troubleshooting.md): Fix installation, agent hooks, browser sessions, remote access, port conflicts, pull request review, HTML, URL, and sharing problems.
- [Artifact Server: A Local Workspace for AI Agent Artifacts](https://docs.plannotator.ai/open-source/artifact-server.md): Browse, edit, annotate, and organize files created by AI agents in one local workspace with MCP and OpenAPI access.
- [Software Planning Templates for People and Coding Agents](https://docs.plannotator.ai/templates/index.md): Copy practical Markdown templates for PRDs, PRFAQs, coding plans, software factory controls, technical specifications, ADRs, RFCs, and agent handoffs.
- [Product Requirements Document Template and Example](https://docs.plannotator.ai/templates/product-requirements-document.md): Copy a complete product requirements document template in Markdown and use a filled, annotated software example to review it.
- [PRFAQ Template: A Complete Working Backwards Example](https://docs.plannotator.ai/templates/prfaq.md): Copy a complete PRFAQ template in Markdown, use a filled fictional software example, and see what reviewers should challenge before a PRD.
- [AI Coding Plan Template](https://docs.plannotator.ai/templates/ai-coding-plan.md): Copy a concise AI coding plan template with scope, implementation steps, risks, validation, and review prompts for a coding agent.
- [Software Factory Control Packet Template and Example](https://docs.plannotator.ai/templates/software-factory-control-packet.md): Copy six Markdown files for intent, context, plan, review, evidence, and decisions in an agent-native software delivery workflow.
- [Technical Specification Template](https://docs.plannotator.ai/templates/technical-specification.md): Copy a technical specification template for requirements, non-goals, architecture, interfaces, data, failure behavior, rollout, and verification.
- [Architecture Decision Record Template](https://docs.plannotator.ai/templates/architecture-decision-record.md): Copy a concise architecture decision record template with status, context, drivers, options, decision, consequences, and confirmation.
- [Software RFC Template](https://docs.plannotator.ai/templates/software-rfc.md): Copy a software RFC template for a proposal that needs broad discussion of motivation, design, alternatives, compatibility, rollout, and open questions.
- [AGENTS.md Template](https://docs.plannotator.ai/templates/agents-md.md): Copy a focused AGENTS.md template for repository purpose, exact commands, local conventions, safety boundaries, verification, and scoped references.
- [Coding Agent Handoff Template](https://docs.plannotator.ai/templates/agent-handoff.md): Copy a coding-agent handoff template that connects the request, revision, changes, validation evidence, deviations, risks, and next action.
- [AI Coding Planning Frameworks](https://docs.plannotator.ai/frameworks/index.md): Choose among source-backed AI coding and planning frameworks, including Amazon Working Backwards, by artifact model, workflow, task grain, review points, and tool coupling.
- [What Is a PRFAQ? Amazon's Working Backwards Method Explained](https://docs.plannotator.ai/frameworks/amazon-working-backwards-prfaq.md): A PRFAQ combines a future press release with customer and internal FAQs. Learn how Amazon's Working Backwards method uses it before product requirements and technical design.
- [Superpowers Planning Framework Profile](https://docs.plannotator.ai/frameworks/superpowers.md): A source-backed profile of Superpowers: brainstorming, reviewed design, repository plans, code-level task grain, TDD, execution, and verification.
- [GSD Core Planning Framework Profile](https://docs.plannotator.ai/frameworks/gsd.md): A source-backed profile of GSD Core: durable project state, milestones, phases, plans, execution summaries, verification, UAT, and handoff files.
- [GitHub Spec Kit Framework Profile](https://docs.plannotator.ai/frameworks/github-spec-kit.md): A source-backed profile of GitHub Spec Kit: constitution, feature specification, plan, research, data model, contracts, tasks, and implementation.
- [Kiro Specs Framework Profile](https://docs.plannotator.ai/frameworks/kiro-specs.md): A source-backed profile of Kiro Specs: requirements-first, design-first, and quick-plan workflows with requirements, design, and task artifacts.
- [Matt Pocock's AI Engineering Skills Profile](https://docs.plannotator.ai/frameworks/matt-pocock-skills.md): A source-backed profile of Matt Pocock's AI engineering skills for specs, tickets, wayfinding, domain modeling, ADRs, and issue-centered planning.
- [BMad Method Framework Profile](https://docs.plannotator.ai/frameworks/bmad-method.md): A source-backed profile of the BMad Method: adaptive delivery tracks, product briefs, PRDs, architecture, epics, stories, and sprint state.
- [Architecture Decision Record Formats](https://docs.plannotator.ai/frameworks/adr-formats.md): Compare MADR, Michael Nygard's ADR form, and a minimal decision-memory form by structure, review need, and durable value.
- [Software Planning Comparisons](https://docs.plannotator.ai/compare/index.md): Use evidence-backed comparisons to choose between planning frameworks and document formats without rankings or unsupported quality claims.
- [Superpowers vs GSD for AI Coding Plans](https://docs.plannotator.ai/compare/superpowers-vs-gsd.md): Compare Superpowers and GSD Core by unit of work, artifact location, lifecycle, task grain, human checkpoints, verification, and session continuity.
- [GitHub Spec Kit vs Kiro Specs](https://docs.plannotator.ai/compare/github-spec-kit-vs-kiro-specs.md): Compare GitHub Spec Kit and Kiro Specs by artifact set, workflow modes, requirement style, task structure, tool coupling, persistence, and reuse rights.
- [ADR vs RFC vs Technical Specification](https://docs.plannotator.ai/compare/adr-vs-rfc-vs-technical-specification.md): Choose an ADR, software RFC, or technical specification by the decision, discussion, authority, lifecycle, and maintenance record you need.
- [PRD vs Technical Specification vs Implementation Plan](https://docs.plannotator.ai/compare/prd-vs-technical-specification-vs-implementation-plan.md): Choose a PRD, technical specification, or implementation plan by whether you need product intent, technical design, or an execution sequence.
- [Learn AI-Assisted Software Planning and Review](https://docs.plannotator.ai/learn/index.md): Practical, source-backed guides to planning and specifications, agent instructions, Markdown collaboration, code review, and AI-development workflows.
- [What Is a Product Requirements Document? How to Write One](https://docs.plannotator.ai/learn/planning/what-is-a-product-requirements-document.md): Learn what a product requirements document is, how to write and review one with people and coding agents, and where technical design begins.
- [Spec-Driven Development for AI Coding Agents](https://docs.plannotator.ai/learn/planning/spec-driven-development-for-ai-coding-agents.md): Learn how spec-driven development turns reviewed requirements, design, tasks, and implementation evidence into durable context for AI coding agents.
- [How to Plan with AI Coding Agents: Find Unknowns Before You Build](https://docs.plannotator.ai/learn/planning/how-to-plan-with-ai-coding-agents.md): Plan with AI coding agents by finding unknowns, testing risky assumptions, recording deviations, and verifying the result against a clear finish line.
- [How to Approve AI Coding Plans Before Execution](https://docs.plannotator.ai/learn/code-context/approve-ai-coding-plan-before-execution.md): Review an AI coding plan in local open-source Plannotator, send precise feedback, compare revisions with Plan Diff, and approve only the current plan.
- [Plan Diff: See What Changed Between Iterations](https://docs.plannotator.ai/learn/plan-diff-see-what-changed.md): Compare an agent's revised plan with an earlier version in rendered or raw diff views, then review only what changed.
- [When Should AI Coding Agents Produce HTML Instead of Markdown?](https://docs.plannotator.ai/learn/code-context/ai-agent-html-vs-markdown.md): Learn when AI coding agents should use HTML artifacts instead of Markdown, with practical tradeoffs for review, security, accessibility, and Git.
- [HTML Wireframes and Prototypes for Coding Agents](https://docs.plannotator.ai/learn/code-context/html-wireframes-and-prototypes-for-coding-agents.md): Design the interface yourself and iterate in the browser before anyone writes production code. Use a coding agent and one HTML file to test structure, visual direction, and interaction.
- [How to Keep Codebase Documentation Current When AI Agents Write Code](https://docs.plannotator.ai/learn/code-context/living-documentation-for-ai-agents.md): A practical workflow for keeping codebase documentation current as AI coding agents plan, implement, test, and revise software.
- [What Is a Claude File? How CLAUDE.md Works](https://docs.plannotator.ai/learn/ai-development/what-is-a-claude-file.md): A CLAUDE.md file gives Claude Code project instructions. Learn when Claude loads it, how nested files work, and how it differs from auto memory.
- [How to Write a Good AGENTS.md (or CLAUDE.md)](https://docs.plannotator.ai/learn/ai-development/how-to-write-a-good-agents-md.md): Learn what to put in AGENTS.md or CLAUDE.md, how coding agents load repository instructions, and how to improve results without bloating the agent's context.
- [Why AI Agents Ignore Instructions and How to Test Them](https://docs.plannotator.ai/learn/ai-development/how-to-test-ai-agent-instructions.md): Learn why AGENTS.md, CLAUDE.md, and SKILL.md guide AI agents without enforcing behavior, and how to test required actions, prohibited actions, and final state.
- [What Is a Coding-Agent Field Guide?](https://docs.plannotator.ai/learn/ai-development/what-is-a-coding-agent-field-guide.md): A coding-agent field guide turns repeated review corrections into evidence-backed project lessons that agents load only for relevant work.
- [How to Compound Feedback with Plannotator](https://docs.plannotator.ai/code-context/compound-with-plannotator.md): Use Plannotator's local compound skill to find repeated plan-review feedback and turn it into review instructions backed by your own archive.
- [What Should an AI Coding Agent Hand Back After It Changes Code?](https://docs.plannotator.ai/learn/code-context/ai-coding-agent-handoff.md): A practical team handoff contract for AI-generated code: the request, exact revision, change map, validation evidence, risks, and documentation impact.
- [How to Annotate a Website or HTML File](https://docs.plannotator.ai/learn/annotate-any-web-page-or-html-file.md): Use Plannotator to annotate a URL, local HTML file, or supported folder and return structured feedback to a coding agent. Use App Notes for live pages.
- [How Teams Understand AI-Generated Code Before Shipping It](https://docs.plannotator.ai/learn/code-context/understand-ai-generated-code-before-shipping.md): A practical workflow for understanding AI-generated code by connecting the approved request, implementation, evidence, review, and final team decision.
- [Local Diff Review for Coding Agents](https://docs.plannotator.ai/learn/local-diff-review-for-coding-agents.md): Open local code changes in Plannotator, add line-specific comments or suggestions, and send structured feedback back to your coding agent.
- [What Is a Revision Diff? A Practical Code Review Guide](https://docs.plannotator.ai/learn/code-review/what-is-a-revision-diff.md): Learn what a revision diff is, how it differs from a pull request diff, and why it makes repeat code reviews faster after authors push new commits.
- [What Are Code Review Artifacts? Screenshots, Video, HTML, and AI Evidence](https://docs.plannotator.ai/learn/code-review/what-are-code-review-artifacts.md): Code review artifacts are screenshots, recordings, HTML, reports, and other evidence reviewed beside a code diff. Learn what GitHub supports and why AI makes these artifacts more important.
- [Review Pull Request Artifacts Beside the Code](https://docs.plannotator.ai/learn/code-review/review-pull-request-artifacts.md): Plannotator gathers screenshots, GIFs, videos, HTML, and Markdown from GitHub pull requests and GitLab merge requests into one artifact gallery beside the code diff.
- [Why AI-Generated Pull Requests Are Harder to Review](https://docs.plannotator.ai/learn/code-review/why-ai-generated-pull-requests-are-harder-to-review.md): Why AI-generated pull requests are harder for teams to review, even with Codex, Cursor, and GitHub. Learn what shared context and evidence are still missing.
- [Stay in the Loop and Own the Quality You Ship](https://docs.plannotator.ai/learn/ai-development/stay-in-the-loop-own-quality.md): Use local plan, document, and code review with open-source Plannotator while Git, GitHub, or GitLab remains the record of the work and shipping decision.
- [What Is an AI Artifact? Definition and Examples](https://docs.plannotator.ai/learn/ai-development/what-is-an-ai-artifact.md): An AI artifact is a reusable output created by an AI system, such as a document, image, application, plan, report, video, or code walkthrough. Learn how artifacts differ from chat responses and how people use them.
- [Claude Artifacts: Examples and How to Use Them](https://docs.plannotator.ai/learn/ai-development/claude-artifacts.md): Learn what Claude Artifacts are, how to create and share them, which forms they support, and how to review exported HTML or Markdown.
- [What Are Rich References for AI Agents?](https://docs.plannotator.ai/learn/ai-development/what-are-rich-references.md): Rich references give AI agents concrete context such as repositories, HTML prototypes, specs, tests, and rubrics instead of longer prompt instructions.
- [What Is Context Rot? Why AI Agents Get Worse Over Time](https://docs.plannotator.ai/learn/ai-development/what-is-context-rot.md): Context rot is the decline in an AI agent's reliability as its working context grows. Learn why it happens, why larger context windows do not fully solve it, and how to reduce it.
- [What Is an LLM Codebase Wiki? Pros, Cons, and Whether You Need One](https://docs.plannotator.ai/learn/ai-development/what-is-an-llm-codebase-wiki.md): An LLM codebase wiki uses AI to generate and maintain documentation about a software repository. Learn how codebase wikis work, where they help, where they create cost or context rot, and how they compare with spec-driven development.
- [What Are Long-Horizon Tasks for AI Agents?](https://docs.plannotator.ai/learn/ai-development/what-are-long-horizon-tasks-for-ai-agents.md): Long-horizon tasks require AI agents to sustain progress across dependent steps, context windows, and checkpoints. Learn how they differ from long-running jobs and how teams prepare them.
- [What Is an AI Software Factory? How Agent-Native Software Delivery Works](https://docs.plannotator.ai/learn/ai-development/what-is-an-ai-software-factory.md): An AI software factory is a repeatable delivery system that turns intent and context into agent-executed, evidence-backed software changes, then learns from the result.
- [What an AI Agent Night Shift Looks Like for Teams](https://docs.plannotator.ai/learn/ai-development/how-teams-run-ai-agent-night-shift.md): A practical team workflow for turning approved plans into code, product artifacts, tests, screenshots, and a morning review packet while AI agents work overnight.