@jacfrost/autopm 0.0.1

package/README.md

@@ -0,0 +1,149 @@
+# AutoPM
+
+AutoPM is a local Product Manager agent runtime for software teams that want an AI assistant to keep product context, objectives, plans, proposal review, release readiness, scheduler jobs, heartbeat work, memory, and opportunity research in one inspectable workspace.
+
+It is packaged as `@jacfrost/autopm` and exposes the `autopm` command. AutoPM runs locally by default, writes local product-management state, and treats external systems as off-limits unless a reviewed command explicitly authorizes that side effect.
+
+## Why It Exists
+
+Coding agents are useful, but product work is usually scattered across prompts, chat history, docs, issue trackers, and half-remembered decisions. AutoPM gives the agent a PM operating layer:
+
+- Product context that can be set up, refreshed, inspected, and kept separate from untrusted source evidence.
+- Objectives that name the current north star and success signals.
+- Reviewable plans, triage proposals, and ship-readiness checks.
+- Local scheduled jobs and proactive heartbeat runs for recurring PM calibration.
+- Reviewed memory and wiki-style recall for durable product knowledge.
+- Opportunity workflows that combine built-in web intake, analysis, skepticism, and PM writing.
+
+## Quickstart
+
+For a published package release:
+
+```sh
+npm install -g @jacfrost/autopm
+autopm --help
+autopm
+```
+
+For repository-local development:
+
+```sh
+git clone https://github.com/juntaochi/autopm.git
+cd autopm
+npm install
+node bin/autopm --help
+node bin/autopm
+```
+
+A healthy launcher reports the AutoPM package identity, user config root, bundled runtime status, and `dev fallback active: no`.
+
+## First Run
+
+Start from the project you want AutoPM to manage:
+
+```text
+/product-setup
+/context status
+/objective set --north-star "Ship a useful first AutoPM workflow" --signal "AutoPM can propose and inspect next actions"
+/objective status
+```
+
+Then use natural language or the command surface:
+
+```text
+/plan prepare the next release
+/triage propose --auto
+/ship check
+/loop list
+/heartbeat status
+/memory status
+/opportunities
+```
+
+AutoPM should ask for missing product facts, write local context, create reviewable proposals, and keep state changes inspectable. It should not deploy, push, publish, create tickets, run OAuth, perform hosted sync, or mutate external systems as a hidden side effect.
+
+## Core Commands
+
+| Command | What it is for |
+| --- | --- |
+| `/bootstrap` | First-run onboarding and prompt-file setup. |
+| `/product-setup` | Guided product-context setup and read-only connector management. |
+| `/context` | Product context status and refresh. |
+| `/objective` | Current PM objective, north star, and success signals. |
+| `/plan` | Natural-language planning and reviewable plan proposals. |
+| `/triage` | Local action proposals and guarded local diagnostic runs. |
+| `/ship` | Local release-readiness checks. |
+| `/loop` | Named local AI scheduled jobs. |
+| `/heartbeat` | Proactive PM calibration status, cadence, and manual runs. |
+| `/memory` | Reviewed memory capture, recall, and diagnostics. |
+| `/opportunities` | PM-facing opportunity research and summaries. |
+
+## Safety Model
+
+AutoPM is designed around inspectable local state and conservative side effects.
+
+- Product context, objectives, plans, scheduler jobs, heartbeat state, memory, and opportunity artifacts belong to the current workspace.
+- User config and model/provider settings belong to the user's AutoPM config root.
+- Connectors are read-only. They are not OAuth grants, hosted sync jobs, ticket integrations, or remote write handles.
+- Product-context sources are untrusted evidence until the agent turns them into reviewed PM narrative.
+- External mutation requires explicit, reviewed authority. Local diagnostics should report what they read, what they wrote, and what the next safe action is.
+
+## Credit And Lineage
+
+AutoPM stands on real upstream work and should be read that way.
+
+- **Pi / pi-coding-agent:** AutoPM uses a bundled Pi-derived agent runtime as its foundation. The standalone AutoPM package removes the need for users to install a global `pi` command, but the runtime lineage and engineering credit belong to Pi and the pi-coding-agent ecosystem by Mario Zechner. The bundled Pi-derived source retains its upstream [MIT license notice](forks/autopm-pi-mono/LICENSE).
+- **pi-skills:** AutoPM bundles Pi-compatible skills for agent capabilities such as web search and browser tooling where applicable. Those skills follow the Pi skill format, retain upstream credit to Mario Zechner, and keep their source and license notices in the bundled [pi-skills source](resources/skills/pi-skills-source/README.md).
+- **Built-in PM skills:** AutoPM's product-management capability is not only command plumbing. It includes a broad built-in PM skill library, credited to Pawel Huryn where applicable, covering work such as PRDs, opportunity-solution trees, positioning, pricing, segmentation, user stories, OKRs, release notes, retros, market sizing, and strategy frameworks. The bundled PM skill source retains its own [MIT license notice](resources/skills/pm-skills-source/LICENSE).
+- **AutoPM layer:** This repository composes those foundations into a standalone PM agent product: package identity, command surface, local state contracts, safety boundaries, runtime dashboard, memory, scheduler, heartbeat, and opportunity workflows.
+
+## Documentation
+
+Start with these docs when you need more detail:
+
+| Topic | Doc |
+| --- | --- |
+| Install, first run, scheduler, heartbeat, memory, diagnostics | [AutoPM Bootstrap Guide](docs/autopm-bootstrap.md) |
+| Command syntax, command boundaries, envelopes, diagnostics | [AutoPM Command Surface](docs/autopm-command-surface.md) |
+| Package loader, bundled runtime, no-local-Pi behavior | [AutoPM Package And Runtime](docs/autopm-package.md) |
+| Product setup, connectors, source safety | [AutoPM Product Setup](docs/product-setup.md) |
+| Runtime dashboard fields and safe next actions | [AutoPM Runtime Dashboard](docs/autopm-runtime-dashboard.md) |
+| Local workspace state contract | [AutoPM Local Workspace Contract](docs/autopm-local-workspace-contract.md) |
+| Memory operator guide | [AutoPM Memory Operator Guide](docs/autopm-memory-operator-guide.md) |
+| Opportunity research workflow | [Venture Signal](docs/venture-signal.md) |
+
+## Development
+
+Use Node.js and npm from the repository root.
+
+```sh
+npm install
+npm test
+```
+
+Focused verifiers are available for the main AutoPM surfaces:
+
+```sh
+npm run verify:autopm-standalone
+npm run verify:autopm-loader
+npm run verify:autopm-command-surface
+npm run verify:autopm-bootstrap
+npm run verify:autopm-memory
+npm run verify:autopm-loop-scheduler
+npm run verify:autopm-heartbeat-state
+npm run verify:autopm-heartbeat-runner
+```
+
+Use the narrow verifier that matches the command family you changed. Treat `npm run verify:autopm-standalone` as the public-ready aggregate proof for install, package boundary, no-local-Pi startup, scheduler, heartbeat, bootstrap, memory, and command-surface behavior.
+
+## Release Status
+
+AutoPM is currently version `0.0.1`. The repository is shaped for public GitHub and npm presentation, with a root README, package metadata, first-run guidance, command map, safety model, documentation index, development commands, and explicit upstream credit.
+
+Before a broad public release, confirm npm package contents with `npm pack --dry-run` and publish only after the standalone verifier passes.
+
+## License
+
+The AutoPM root package is currently `UNLICENSED`. Public npm distribution does not grant open-source reuse rights unless a future root license is added.
+
+Bundled upstream components and skill sources retain their own license notices and attribution, including the Pi-derived runtime, pi-skills, and the built-in PM skill source.

package/bin/autopm

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runAutopmEntrypoint } from '../src/autopm/loader.js';
+
+await runAutopmEntrypoint();

package/docs/autopm-bootstrap.md

@@ -0,0 +1,327 @@
+# AutoPM BOOTSTRAP.md
+
+This workspace bootstrap file is active agent guidance. While it exists, begin onboarding in natural language even if the operator only greets you or asks who you are. Say you are AutoPM, then immediately walk the operator through setup from the checklist below.
+
+Check each row, help the operator through any missing setup, and delete `.autopm/BOOTSTRAP.md` yourself only after every row is verified or explicitly not needed. Do not wait for system detection.
+
+| Check | What to verify | Command or evidence | Done when |
+| --- | --- | --- | --- |
+| Product context | The workspace has a clear product brief and trusted local sources. | `/context status`, `/product-setup` | Product context is present and current, or the next setup step is clear. |
+| Objective | The current product objective is explicit and actionable. | `/objective status` | Objective is present, or the operator has been asked to choose or refine one. |
+| Bootstrap flow | The operator understands the AutoPM flow and available commands. | `/bootstrap start`, this file | The agent has explained setup, daily work, and completion in natural language. |
+| Context inventory | System prompt files, product context, memory, and runtime status are visible. | `/context status` | Missing items are named without exposing raw sensitive content. |
+| Heartbeat and scheduler | Proactive loop status is known. | `/heartbeat status`, `/loop status` | The agent can state whether proactive work is enabled and what the next safe action is. |
+| Memory | Dedicated AutoPM memory status is known. | `/memory status` | Memory is checked through `.autopm/memory/`, not `MEMORY.md`. |
+| Proposals and triage | Reviewable proposal paths and intake triage are known. | `/plan`, `/triage`, local proposal artifacts | The agent can propose next work without mutating remote systems. |
+| Shipping readiness | Verification and release-readiness checks are understood. | `/ship status`, tests or local diagnostics | The agent knows the evidence needed before claiming readiness. |
+| Connectors | Local connector state is understood. | `/product-setup list` | External integrations stay read-only unless explicitly authorized. |
+| Safety | No hidden deploy, push, publish, OAuth, or remote mutation will happen. | Local command output and operator authorization | External side effects require explicit reviewed authorization. |
+
+## Agent Completion Rule
+
+When every row above is checked or explicitly not needed for this workspace, delete `.autopm/BOOTSTRAP.md` yourself. The runtime will not decide that for you.
+
+## Full AutoPM Bootstrap Guide
+
+This guide is for a new AutoPM operator starting from a standalone install. After reading it, you should be able to launch AutoPM, create local product context, inspect the runtime dashboard, schedule a named job with `/loop`, configure proactive heartbeat work with `/heartbeat status`, `/heartbeat on`, `/heartbeat off`, and `/heartbeat interval`, initialize memory when you want it, and choose safe next actions when first-run warnings appear.
+
+AutoPM is a local product-management agent runtime. It combines local product context, objective tracking, proposal workflows, a named scheduler, proactive heartbeat runs, reviewed memory, and trusted workspace prompt files. AutoPM is local/manual by default: it can write its own local state, but it does not deploy, push, publish, create tickets, run OAuth, perform hosted sync, or mutate external systems unless a future reviewed command explicitly says so.
+
+## 1. Install and launch
+
+Install through the supported AutoPM package channel, then run the `autopm` binary from the project you want AutoPM to help with:
+
+```sh
+autopm --version
+autopm --help
+autopm
+```
+
+For repository-local development, use:
+
+```sh
+./bin/autopm --version
+./bin/autopm --help
+./bin/autopm
+```
+
+A healthy standalone launch reports AutoPM identity, package/config roots, runtime source, and `dev fallback active: no` in help or startup diagnostics. AutoPM keeps provider auth, model config, settings, and sessions under the user config root `~/.autopm/agent/` by default, so a provider configured once is available in every workspace. The current workspace's `.autopm/` directory remains project state for product context, objectives, plans, scheduler jobs, heartbeat, memory, and Venture Signal artifacts. `AUTOPM_CONFIG_ROOT` overrides only the user config root for development or tests.
+
+### No-local-Pi guarantee
+
+Normal AutoPM releases do not require a preinstalled local `pi` command. The package owns its loader, config identity, resources, and bundled AutoPM runtime. If the bundled runtime is missing or broken, AutoPM should fail closed with AutoPM reinstall guidance instead of silently using a global Pi install.
+
+`AUTOPM_ALLOW_GLOBAL_PI_FALLBACK=1` is development-only. Use it only when intentionally debugging against a separate global Pi runtime; do not use it as normal setup advice for standalone users.
+
+### Model/provider setup is separate
+
+Standalone AutoPM removes the local-Pi prerequisite. It does not remove the need for a model provider or local model configuration. If the agent cannot answer or run model-backed work, configure your model/provider credentials or local model runtime according to your chosen provider. Keep that setup separate from AutoPM install diagnostics: a model auth error is not proof that AutoPM fell back to Pi or that the package install is broken.
+
+## 2. First-run commands
+
+If the startup dashboard says bootstrap is recommended, begin the guided walkthrough first:
+
+```text
+/bootstrap start
+```
+
+When a workspace has `.autopm/BOOTSTRAP.md`, AutoPM injects that file as trusted workspace onboarding while it exists. The agent should not merely answer greetings or identity questions; it should say it is AutoPM and immediately begin walking you through setup in natural language. The walkthrough should proceed one small step at a time, then ask whether you understand the core commands and local-state boundaries. After every checklist row in `.autopm/BOOTSTRAP.md` is verified or explicitly not needed, the agent deletes `.autopm/BOOTSTRAP.md` itself.
+
+For the package fallback guide, after you confirm the walkthrough is understood, mark onboarding complete:
+
+```text
+/bootstrap complete
+```
+
+That keeps `docs/autopm-bootstrap.md` on disk for reference but stops injecting the package fallback guide into future sessions. Use `/bootstrap reset` if you want the fallback guided walkthrough again.
+
+Start with the smallest local setup loop:
+
+```text
+/product-setup
+/context status
+/objective set --north-star "Ship a useful first AutoPM workflow" --signal "AutoPM can propose and inspect next actions"
+/objective status
+```
+
+Use `/product-setup` when you want guided onboarding. Use explicit targets when you already know the source:
+
+```text
+/product-setup .
+/product-setup ./docs
+/product-setup https://example.com/product
+```
+
+In the interactive TUI, `/product-setup` opens on the search/input prompt. The first menu action is `Start guided setup`, which hands off to the AI-guided product setup workflow; use `List product connectors` and `Refresh product context` when you only want connector inspection or refresh.
+
+Product setup writes local product context under `.autopm/product-context/`. Local files and safe public pages are treated as untrusted evidence and are redacted before they appear in runtime context.
+
+If your product context has more than one source, register read-only connectors:
+
+```text
+/product-setup add --id docs --target ./docs
+/product-setup add --id public-page --target https://example.com/product
+/product-setup list
+/product-setup refresh
+```
+
+Connector setup is read-only. It does not create OAuth grants, credentials, hosted sync, paid integrations, tickets, or remote writes.
+
+## 3. Read the startup dashboard
+
+On launch, AutoPM shows a runtime dashboard and writes a redacted status snapshot when possible. Use it as the first diagnostic surface before changing state.
+
+Important local artifacts:
+
+| Surface | What to inspect | Safe action |
+|---|---|---|
+| Runtime dashboard | `.autopm/runtime/status.json` | Follow its `safeNextActions`, usually `/product-setup`, `/context status`, `/objective status`, `/loop list`, or `/heartbeat status`. |
+| Product context | `.autopm/product-context/index.json` and `.autopm/product-context/intro.md` | Run `/context status`, then `/context refresh [target]` if missing or stale. |
+| Objective | `.autopm/objective/current.json` | Run `/objective status` for inspection; for normal planning, tell `/plan` the target in natural language and let the agent create or update the objective internally. |
+| Scheduler | `.autopm/scheduler/jobs.json` and `.autopm/scheduler/jobs-state.json` | Run `/loop list` or `/loop list`. |
+| Heartbeat | `.autopm/heartbeat/state.json` | Run `/heartbeat status`; configure the interval or turn it on when ready. |
+| Memory | `.autopm/memory/` and `.autopm/wiki/` | Run `/memory status`; initialize only when you want reviewed local recall. |
+
+Runtime snapshots are diagnostic surfaces, not sources of truth. Repair the owning state through the command listed for that surface.
+
+## 4. Core command flow
+
+A typical local AutoPM workflow is:
+
+1. **Ground the product:** `/product-setup` or `/context refresh <target>`.
+2. **Plan in natural language:** use `/plan <what you want to accomplish>`; the agent should infer or update the objective and create a reviewable local plan proposal when the target is clear.
+3. **Inspect readiness:** `/context status`, `/objective status`, and the startup dashboard when you need deterministic diagnostics.
+4. **Generate proposals:** use `/triage propose --from venture` for signal-driven proposals, or let the agent use `/plan propose` internally after objective state is ready.
+5. **Review before run:** inspect proposals with `/triage show --proposal-id <id>` or `/plan show --proposal-id <id>`.
+6. **Check ship readiness:** `/ship check [--proposal-id <id>]` for local readiness diagnostics only.
+7. **Automate local reminders:** use `/loop` for named scheduled jobs and explicit `/heartbeat ...` subcommands for proactive HEARTBEAT.md runs.
+
+Prefer native AutoPM commands first. Removed feed compatibility commands are not part of the product surface.
+
+## 5. `/loop`: AI-mediated local scheduled jobs
+
+`/loop` is the AutoPM scheduler for named local AI scheduled jobs under `.autopm/scheduler/`. It is not the old managed heartbeat loop, not a remote scheduling service, and not a shell-command runner.
+
+AutoPM scheduler jobs use this local shape:
+
+- `title` / `name`: a short human-readable job title.
+- `schedule`: a cron expression or supported local recurrence.
+- `message` / `body`: the concrete `agentTurn` instructions the AI should execute when the job fires.
+
+Natural-language `/loop ...` input is intentionally **AI-mediated**. The extension does not infer title, schedule, or message/body directly from prose. It sends a concise request to the AI instead. The AI should extract title, schedule, and operation body; if any field is unclear, it should ask one concise clarification. Once the fields are clear, the AI uses the scheduler tool with explicit fields.
+
+Public command:
+
+```text
+/loop list
+```
+
+`/loop list` is the only public deterministic `/loop` subcommand. It inspects existing jobs and returns ids, titles, bodies, schedules, next trigger times, enabled state, latest run status, artifact paths, and redacted diagnostics. To create, edit, pause, resume, remove, or run a job, tell the AI what you want in natural language; the AI will clarify missing fields and then use the scheduler tool internally.
+
+Natural-language example:
+
+```text
+/loop 帮我每周晚上五点做一个夜晚小结
+```
+
+In the interactive TUI, `/loop` opens with the input prompt highlighted. Type to describe a new scheduled task and press Enter to create through the AI-mediated flow, or press Down to move into existing scheduled jobs. While a job is selected, Space toggles pause/resume in place without closing the menu; Up from the first job returns to the input prompt.
+
+Expected AI behavior for that example:
+
+1. Interpret the requested recurrence and body.
+2. Ask if the schedule or body is ambiguous.
+3. If clear, use the scheduler tool with explicit fields, for example `--title "夜晚小结"`, `--schedule "cron 0 17 * * 1"`, and a full `--message` body describing what the AI should summarize when the job fires.
+
+Accepted schedule inputs are intentionally small: one-shot ISO times, `every <number> minute(s)|hour(s)|day(s)`, and simple five-field cron expressions with UTC, local, or a valid IANA timezone.
+
+When a scheduler command warns about malformed state, inspect `.autopm/scheduler/jobs.json`, `.autopm/scheduler/jobs-state.json`, and the returned `warningCodes` or `errorCodes`. Do not repair by switching to removed compatibility surfaces.
+
+## 6. Heartbeat Commands: proactive PM calibration
+
+The heartbeat command family controls proactive interval-based PM calibration. The public surface is `/heartbeat status`, `/heartbeat on`, `/heartbeat off`, `/heartbeat interval <minutes>`, and `/heartbeat now`; `/heartbeat show` and `/heartbeat last` are not public commands. Its state lives in `.autopm/heartbeat/state.json`. First active AutoPM session startup creates `.autopm/HEARTBEAT.md` from `docs/autopm-heartbeat.md` with the other `.autopm/` prompt templates and records that one-time initialization; `/heartbeat on` does not create prompt files. A heartbeat run looks for `.autopm/HEARTBEAT.md` first, then root `HEARTBEAT.md` if the preferred file is absent. Empty or placeholder-only files are skipped quietly and recorded as a redacted `lastRun` summary. `/heartbeat status` is a local read-only viewer for redacted heartbeat run summaries; heartbeat agent runs use an isolated heartbeat session and do not send messages to, compact, or navigate the main conversation.
+
+Start with inspection, then set a cadence:
+
+```text
+/heartbeat status
+/heartbeat interval 120
+/heartbeat on
+/heartbeat now
+/heartbeat status
+```
+
+To run every 30 minutes instead:
+
+```text
+/heartbeat interval 30
+/heartbeat status
+```
+
+Use HEARTBEAT.md for bounded local instructions that tell the agent how to be proactive. The default template is deliberately second-person and judgment-based: each tick should choose one useful mode, not run a fixed checklist.
+
+- Cross-validate information across product context, objective, memory, opportunity evidence, recent artifacts, and repository signals.
+- Do deeper topic research when a narrow question would change a PM decision.
+- Take or propose the smallest safe local PM action when the next step is clear.
+- At low frequency, run a self-gap check and ask one calibration question when AutoPM's current harness may not match the user's target.
+
+Self-gap questions should be rare and evidence-triggered, not noise. Good examples are: "Am I good enough for the product direction you currently want me to support?", "Do you think my current information sources have a gap relative to where this product is going?", or "Is the objective I am optimizing for still the one you care about?" When nothing deserves interruption, the heartbeat returns `HEARTBEAT_OK`. Do not put secrets in HEARTBEAT.md. Persisted heartbeat summaries are redacted, but the file is still local prompt input and should be safe to inspect.
+
+Native `/heartbeat now` is the manual proactive HEARTBEAT.md runner. Old status synthesis and legacy managed-loop compatibility are removed from the product surface.
+
+Heartbeat is intentionally subcommand-only, not menu-first: `/heartbeat status` inspects status, `/heartbeat on` enables the proactive runner, and `/heartbeat off` stops it. Short command menus such as `/triage` use a direct action list without a search prompt.
+
+## 7. Memory
+
+AutoPM memory is explicit and reviewed. The command surface is package-owned, but memory state belongs to the current workspace under `.autopm/memory/` and `.autopm/wiki/`.
+
+Memory is prepared automatically on session start when the workspace only needs bootstrap files. Normal operator commands:
+
+```text
+/memory status
+/memory recall
+/memory ingest all
+/memory candidates
+/memory accept <candidateId>
+/memory doctor
+```
+
+A missing memory store is usually a setup warning, not a broken install. Initialize memory only when you want AutoPM to build reviewed local recall. AutoPM does not automatically learn from chat text, ingest sources, or accept candidates during normal conversation. `/loop` and heartbeat commands should not silently run memory maintenance unless a future explicit, documented command path enables it.
+
+## 8. Skills, tools, and command categories
+
+AutoPM exposes three related capability surfaces:
+
+- **Commands** are operator-facing actions you type, such as `/product-setup`, `/loop`, or `/heartbeat status`.
+- **Tools** are agent-callable functions behind workflows, such as AutoPM scheduler tools, Venture Signal tools, product setup tools, and AutoPM memory tools. They should be invoked through documented commands or reviewed agent work rather than treated as first-run setup chores.
+- **Skills** are specialized operating manuals for the agent. A skill tells the agent how to run a class of work well; it is not a setup task every new user must learn before starting AutoPM.
+
+Use this map to choose the right surface by intent:
+
+| Category | Start here | Representative skills/tools |
+|---|---|---|
+| Core AutoPM flow | Ground the product, set objectives, inspect readiness, propose plans, check local ship readiness, schedule AI-mediated jobs, and run HEARTBEAT.md work. | Commands: `/bootstrap`, `/product-setup`, `/context`, `/objective`, `/triage`, `/plan`, `/ship`, `/loop`, `/heartbeat status`, `/heartbeat on`, `/heartbeat off`, `/heartbeat interval`, `/heartbeat now`, `/memory`. Skills: `product-setup`, `daily-brief`. Tools: AutoPM scheduler tools, AutoPM memory tools, and Venture Signal tools. |
+| Coding quality | Add or review tests, linting, TDD loops, code review, security review, performance checks, and failure-handling improvements. | Skills: `test`, `lint`, `tdd`, `review`, `security-review`, `code-review-excellence`, `error-handling-patterns`, `code-optimizer`. |
+| Product and design | Shape product context, product proposals, interfaces, frontend polish, accessibility, and web quality. | Skills: `product-setup`, `daily-brief`, `frontend-design`, `make-interfaces-feel-better`, `accessibility`, `react-best-practices`, `web-quality-audit`. Commands: `/opportunities`, `/brief run`. |
+| Browser, files, and docs automation | Interact with websites, produce or inspect documents, work with spreadsheets, and write durable docs. | Skills: `agent-browser`, `pdf`, `docx`, `pptx`, `xlsx`, `write-docs`. |
+| GSD planning helpers | Turn discussion into milestone briefs, decompose work into slices, stress-test plans, preserve handoffs, and verify before completing work. | Skills: `write-milestone-brief`, `decompose-into-slices`, `grill-me`, `handoff`, `verify-before-complete`, `spike-wrap-up`. |
+| Extension and local tooling | Inspect package-owned extension behavior and local runtime health. | Commands: `/bootstrap`, `/context`, `/memory doctor`. Tools: AutoPM product setup, scheduler, Venture Signal, and memory tools. |
+
+Command names are the stable thing to memorize first. Skill availability depends on the installed AutoPM resource bundle and operator configuration, so the examples above are representative rather than a required complete list.
+
+Commands return structured envelopes with `status`, `warningCodes`, `errorCodes`, `artifactPathsRead`, `artifactPathsWritten`, `durableStateChanged`, and `nextAction` when applicable. Prefer those fields over notification prose when diagnosing behavior.
+
+## 9. Common warnings and safe next actions
+
+| Symptom or code | Meaning | Safe next action |
+|---|---|---|
+| Missing product context, `AUTOPM_PRODUCT_SETUP_CONNECTORS_MISSING`, or stale context | AutoPM has little or outdated product grounding. | Run `/product-setup`, `/product-setup list`, or `/context refresh [target]`. |
+| `AUTOPM_CONTEXT_REFRESH_TARGET_REQUIRED` | Refresh has no reusable safe source target. | Provide an explicit local path or safe public URL: `/context refresh ./docs`. |
+| `AUTOPM_CONTEXT_REFRESH_TARGET_UNSAFE` or connector target safety errors | The target is private, credential-bearing, localhost/private network, or otherwise unsafe. | Use a bounded local export or safe project-relative file instead. |
+| `AUTOPM_OBJECTIVE_MISSING` | No active local objective exists. | Run `/objective set --north-star <outcome> --signal <measure>`. |
+| Scheduler malformed JSON warnings | The scheduler store cannot be parsed safely. | Inspect `.autopm/scheduler/jobs.json` and `.autopm/scheduler/jobs-state.json`; keep a copy before manual repair. |
+| Heartbeat stopped, paused, missing, or skipped | Proactive heartbeat is not running or HEARTBEAT.md has no executable content. | Run `/heartbeat status`, `/heartbeat interval <minutes>`, `/heartbeat on`, then review `.autopm/HEARTBEAT.md`. |
+| Memory missing | Reviewed local recall has not been initialized. | AutoPM initializes the local memory workspace on session start; inspect `/memory status` or `/memory doctor` if it still reports missing. |
+| Missing bundled runtime or install-broken diagnostic | The standalone package cannot find its own runtime. | Reinstall or rebuild AutoPM. Do not fix release installs by enabling global Pi fallback. |
+| Model authentication/provider errors | AutoPM launched, but the chosen model provider is not configured. | Configure the selected model provider or local model runtime; keep this separate from AutoPM package install repair. |
+| Unsupported public `/loop tick` guidance | `/loop` is now list-only plus AI-mediated scheduled-task creation, not heartbeat execution. | Use `/heartbeat now` for HEARTBEAT.md work. |
+
+If a command returns `durableStateChanged: false`, it did not change behavior-changing local state. If it returns artifact paths, inspect those paths before retrying or running a follow-up command.
+
+## 10. Diagnostics and verification
+
+Use focused diagnostics before assuming the install is broken:
+
+```text
+/context status
+/objective status
+/loop list
+/heartbeat status
+/memory status
+```
+
+For repository development, the main verification commands are:
+
+```sh
+npm run verify:autopm-standalone
+npm run verify:autopm-loader
+npm run verify:autopm-resources
+npm run verify:autopm-no-pi
+npm run verify:autopm-loop-scheduler
+npm run verify:autopm-heartbeat-state
+npm run verify:autopm-heartbeat-runner
+npm run verify:autopm-r020
+```
+
+Use the focused verifier that matches the failing command family. `verify:autopm-r020` is the broad command-surface health signal for product setup, context, triage, plan, ship, loop, and heartbeat.
+
+For release closeout, use `npm run verify:autopm-standalone` as the public-ready aggregate proof. It composes the standalone package contract, loader, resource ownership, no-local-Pi entrypoint behavior, scheduler, heartbeat state/runner, bootstrap docs, package metadata, command-surface compatibility, and memory regressions, then prints named phase summaries with requirement evidence for R036-R038.
+
+## 11. Safe next actions
+
+When in doubt, choose read-only inspection first:
+
+```text
+/context status
+/objective status
+/loop list
+/heartbeat status
+/memory status
+```
+
+Then take the smallest local repair action:
+
+- Missing context: `/product-setup` or `/context refresh <target>`.
+- Missing objective: tell `/plan` the planning target in natural language; the agent should create or update the objective internally before creating a proposal.
+- Need a recurring AI scheduled job: use natural language like `/loop 帮我每周晚上五点做一个夜晚小结`; in the TUI, type the request into the highlighted prompt. The AI should extract or ask for title, schedule, and body, then use the scheduler tool. Use `/loop list` only to inspect existing jobs.
+- Need proactive periodic work: review or customize `.autopm/HEARTBEAT.md`, then run `/heartbeat interval <minutes>` and `/heartbeat on`.
+- Need memory: AutoPM prepares the local store automatically; run `/memory status`, then ingest and accept candidates explicitly.
+- Need release confidence: `/ship check` for local readiness diagnostics only.
+
+Do not bypass AutoPM warnings by switching to hidden global Pi state, remote mutation, or broad shell execution. AutoPM is useful when its local state and command envelopes stay inspectable.
+
+## Related docs
+
+- [AutoPM Command Surface](./autopm-command-surface.md) for complete command syntax, side effects, envelopes, and diagnostic fields.
+- [AutoPM Local Workspace Contract](./autopm-local-workspace-contract.md) for the source-of-truth boundaries of `.autopm/` state.
+- [AutoPM Package and Runtime](./autopm-package.md) for package loader, bundled runtime, standalone no-local-Pi behavior, and development fallback details.
+- [AutoPM Runtime Dashboard](./autopm-runtime-dashboard.md) for startup dashboard fields, runtime status snapshots, and safe-next-action behavior.

package/docs/autopm-command-surface.md

@@ -0,0 +1,73 @@
+# AutoPM Command Surface
+
+AutoPM exposes one product command set. Commands should present AutoPM as a Product Manager agent and should not route through removed compatibility commands.
+
+First-run workspaces should start with the [AutoPM Bootstrap Guide](./autopm-bootstrap.md). The startup dashboard keeps only a compact bootstrap pointer and references `docs/autopm-bootstrap.md` instead of expanding all setup text inline.
+
+| Command | Purpose | State |
+| --- | --- | --- |
+| `/bootstrap` | First-run onboarding and prompt-file setup | `.autopm/bootstrap/` |
+| `/product-setup` | Implemented native product-context setup and read-only connector management (`add`, `list`, `refresh`; connectors.json, index.json, intro.md) | `.autopm/product-context/` |
+| `/context` | Product context status/refresh | `.autopm/product-context/` |
+| `/objective` | Implemented native project-objective command family (`status`, `show`, `set`, `update`; objective state stays under `.autopm/objective/current.json`). No `/objective` subcommand creates removed compatibility workspace state. | `.autopm/objective/current.json` |
+| `/plan` | Reviewable plan proposals | `.autopm/plans/proposals/` |
+| `/triage` | Local action proposals. Implemented native action-proposal command family (`list`, `show`, `propose`, `accept`, `run`; legacy delegation: None.) | `.autopm/actions/proposals/` |
+| `/ship` | Local ship readiness checks | `.autopm/ship/readiness/` |
+| `/loop` | Named AutoPM scheduler jobs | `.autopm/scheduler/` |
+| `/heartbeat status`, `/heartbeat on`, `/heartbeat off`, `/heartbeat interval <minutes>`, `/heartbeat now` | Heartbeat state, cadence, and manual HEARTBEAT.md execution; status lists heartbeat summaries and opens the selected full redacted heartbeat session without sending prompts to the main session | `.autopm/heartbeat/state.json`, `.autopm/heartbeat/runs.json` |
+| `/brief` | AutoPM daily brief placeholder and future brief workflow | local AutoPM runtime context |
+| `/memory` | AutoPM memory capture, review, recall | `.autopm/memory/`, `.autopm/wiki/` |
+| `/opportunities` | PM-facing Venture Signal summaries | `.autopm/venture-signal/` |
+
+## Thin Natural-Language Entry Points
+
+The primary operator UX is a thin natural-language native entrypoint for product workflows:
+
+- `/product-setup` collects or updates product context; if facts are missing, the agent asks one concise clarification or uses current repository/product context before calling internal setup tools. Connector `add`, `list`, and `refresh` remain internal advanced operations. They are read-only or local-write only: no OAuth, no remote writes, no external mutation, no hosted sync, no paid/gated integrations, and source bodies are untrusted.
+- `/objective` creates, reviews, or updates the current PM objective from natural language. Empty `/objective` opens the objective workflow instead of dumping status. Internal `status`, `show`, `set`, and `update` remain available for machine-facing inspection and tests.
+- `/plan` is natural-language first. Use `/plan <planning target>` or bare `/plan` to hand planning to the AutoPM agent; the agent should clarify only when needed, create or update objective state internally, and then use deterministic proposal commands.
+- `/ship` asks whether the current work can be released. The agent should inspect objective, product context, plan proposals, readiness artifacts, and repository state, then report blockers and safe next actions. Internal `status`, `check`, and `show` remain advanced operations.
+- `/triage` turns local signals into reviewable action proposals. Creating a proposal can be local-only when intent is clear; accepting or running a proposal requires explicit operator confirmation.
+- `/memory` remembers, recalls, reviews, or explains project memory from natural language. Durable acceptance requires clear operator intent; internal review and diagnostic commands remain advanced operations.
+
+These commands suppress raw native handoff envelopes in the UI. The operator should not need to learn flags or subcommands to continue these workflows; explicit deterministic subcommands are compatibility and advanced surfaces, not the primary UX.
+
+Advanced/internal compatibility commands remain available for verifiers and tool-mediated flows: `/product-setup add --id <id> --target <target>`, `/product-setup list`, `/product-setup refresh`, `/objective status`, `/objective show`, `/objective set --north-star <text> --signal <text>`, and `/objective update [--north-star <text>] [--signal <text>...] [--constraint <text>...]`. Objective state lives at `.autopm/objective/current.json`; `status` and `show` are read-only and report `durableStateChanged: false`; `set` and successful `update` write only the native AutoPM objective artifact. Product connector diagnostics include `AUTOPM_PRODUCT_SETUP_CONNECTORS_MISSING`, `AUTOPM_PRODUCT_SETUP_CONNECTOR_PARTIAL_FAILURE`, and `AUTOPM_CONNECTOR_TARGET_PRIVATE`. Objective diagnostics include `AUTOPM_OBJECTIVE_MISSING`, `AUTOPM_OBJECTIVE_PARSE_FAILED`, and `AUTOPM_OBJECTIVE_*`. Envelopes preserve `freshnessStatus`, `artifactPathsRead`, `artifactPathsWritten`, and `durableStateChanged`, and redact credential-like text. Secret-looking values are preserved only in `.autopm/objective/current.json` when the operator explicitly writes them. R020, R021, and R023 coverage remains local-only. Objective coverage is `npm run verify:autopm-objective`.
+
+## Action Triage
+
+`/triage` is the native AutoPM feed-to-action boundary; it does not call removed compatibility commands. Deterministic forms are:
+
+```text
+/triage list
+/triage show --proposal-id <id>
+/triage propose (--auto | --item-id <item-id>) [--command-id <command-id>]
+/triage accept --proposal-id <id> [--rationale <text>]
+/triage run --proposal-id <id> [--command-id <command-id>]
+```
+
+The common local proposal path is `/triage propose --auto`. Proposal artifacts live at `.autopm/actions/proposals/<proposal-id>.json` and include `proposalId`, `proposalPath`, `source`, `selection`, `statusHistory`, `approval`, and optional `runAttempt` or `runAttempts` records. Command envelopes report `delegatedLegacyCommand: null`, `artifactPathsRead`, `artifactPathsWritten`, and redacted diagnostics.
+
+Accepted proposals move to `accepted`. Guarded runs append `runAttempts` and move status to `ran` or `run_failed`. Guarded execution is intentionally narrow: current local diagnostics such as `git-status-short` run with `shell: false`, a timeout, and an output cap. Unsupported or unsafe command requests report `AUTOPM_ACTION_PROPOSAL_UNSUPPORTED_COMMAND`; attempts to run before acceptance report `AUTOPM_ACTION_PROPOSAL_NOT_ACCEPTED`. The command text stored on `proposedAction.command` is descriptive metadata, not the executed shell string.
+
+Action triage does not mutate removed compatibility latest/feed/dig artifacts. Proposal creation validates those JSON artifacts when used as sources, but the only durable writes are proposal artifacts under `.autopm/actions/proposals/`. Coverage is `npm run verify:autopm-s03`.
+
+## Venture And Opportunities Boundary
+
+`/opportunities` is the only operator-facing opportunity command and one conversational entrypoint. Bare `/opportunities` and `/opportunities <natural language>` hand the request to the agent through a one-shot hidden context hook, so the agent starts with world intake using built-in web tools, frames multiple opportunity hypotheses, challenges them, and produces an AI-authored product-research brief. Existing PM Writer artifacts and Venture Signal scores are evidence only, not final judgment. Scripts validate and preserve evidence; AI owns judgment.
+
+Venture Signal remains an internal evidence substrate through `venture_signal_*` tools and `.autopm/venture-signal/` artifacts. It should not be registered as a slash command, shown in command menus, listed in launcher help, or suggested as an operator next action.
+
+## Loop And Heartbeat Boundary
+
+`/loop` is scheduling. The heartbeat command family is cadence and HEARTBEAT.md execution. Heartbeat execution is owned by the runtime and bottom heartbeat panel. The only operator-facing heartbeat viewer is `/heartbeat status`: it opens a local TUI with heartbeat summaries, Enter opens the selected full redacted heartbeat session, and Esc exits the viewer. Heartbeat runs use an isolated heartbeat agent session when an agent run is available; they do not send prompts to the main session, summarize or compact the main conversation, or change main-session navigation.
+
+Registered heartbeat commands: `/heartbeat` plus exact entries for `/heartbeat status`, `/heartbeat on`, `/heartbeat off`, `/heartbeat interval`, and `/heartbeat now`. `/heartbeat show` and `/heartbeat last` are not command-surface entries.
+
+## Tool Boundary
+
+Agent-callable tools are AutoPM-owned: `autopm_loop`, `autopm_product_setup`, Venture Signal tools, and memory tools. The manifest should not expose removed feed tools or compatibility modules.
+
+## Verification
+
+M010 standalone release closeout verification is `npm run verify:autopm-standalone`. Treat it as the aggregate release proof and requirement evidence map for R036-R038 after command-surface, scheduler, heartbeat, memory, and package-boundary changes.