productfoo 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Rachel Wolan
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,339 @@
-# Temporary Holding Version
+# productfoo: FSD for your coding agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+productfoo is an agentic product management harness you don’t have to micromanage. productfoo shapes the plan, checks the work, and brings you the decisions that matter. productfoo systematizes the art and science of product management.
+
+Coding agents can move quickly. Keeping them pointed at the right problem takes work: explaining the goal, challenging assumptions, reviewing the result, and picking up the thread in the next session.
+
+productfoo gives that work a repeatable process. You agree on the destination, scope, and checks. Your coding agent builds against that agreement. Decisions, tasks, and evidence stay in your repository, where you and the next agent can inspect them.
+
+You talk to your coding agent the way you already do. The agent runs productfoo.
+
+<!--
+Link convention: productfoo's README is rendered on GitHub, on npmjs.com, and in an
+unpacked tarball. npm does not reliably rewrite relative links, so every
+cross-file link in tarball-shipped files (README.md, docs/CHANGELOG.md,
+docs/THIRD_PARTY_NOTICES.md) is an absolute GitHub URL; other docs/ files (GitHub-only)
+use relative links. The diagrams are plain text so they render the same on
+GitHub, on npm, and in a terminal.
+-->
+
+## How it works
+
+Everything flows toward one artifact, the productfoo Spec. The coding agent builds
+against it, and reconciliation compares the result back to it. People make the
+calls shown in brackets.
+
+```text
+SIGNAL                     EXPLORE                       SHAPE
+┌───────────────────────┐  ┌──────────────────────────┐  ┌─────────────────────────┐
+│ Customer calls        │─▶│ foo discovery            │─▶│ foo spec                │
+│ approved sources only │  │ evidence, no transcripts │  │ asks only the questions │
+└───────────────────────┘  └──────────────────────────┘  │ that matter             │
+┌───────────────────────┐  ┌──────────────────────────┐  │                         │
+│ Public research       │─▶│ foo research             │─▶│ foo roast               │
+│ labeled untrusted     │  │ sealed, cited paper      │  │ cuts weak scope         │
+└───────────────────────┘  └──────────────────────────┘  │                         │
+┌───────────────────────┐  ┌──────────────────────────┐  │ foo preview             │
+│ An idea or request    │─▶│ foo ideate · pitch       │─▶│ see it before build     │
+│ rough is fine         │  │ shortlist · GO / NO-GO   │  │                         │
+└───────────────────────┘  └──────────────────────────┘  │ [ you agree it ]        │
+                                                         └────────────┬────────────┘
+      ┌───────────────────────────────────────────────────────────────┘
+      ▼
+THE CONTRACT                                   BUILD AND PROVE
+┌─────────────────────────────┐                ┌──────────────────────────┐
+│ productfoo Spec             │ tasks + checks │ Coding agent builds      │
+│ specs/<packet>/             │ ─────────────▶ │ own branch + worktree    │
+│ Intent                      │                └─────────────┬────────────┘
+│ Decisions + open questions  │                              ▼
+│ Agreed, suggested, and      │                ┌──────────────────────────┐
+│   discovered work           │     drift      │ foo reconcile            │
+│ Tasks + acceptance checks   │ ◀───────────── │ diff vs. agreed spec     │
+│ Proof + event history       │                └─────────────┬────────────┘
+└─────────────────────────────┘                              ▼ proven
+                                               ┌──────────────────────────┐
+                                               │ Pull request → ship      │
+                                               │ [ you approve ]          │
+                                               └──────────────────────────┘
+```
+
+Signal moves left to right into the productfoo Spec. The coding agent builds from that
+spec, and `foo asp reconcile` compares the implementation evidence with it. The
+diagrams use “foo reconcile” as shorthand for this step. Drift goes back to the spec
+for a decision. Work backed by proof goes to a person for approval.
+
+## Get started
+
+For the CLI, you need Node.js 18 or newer, npm, Git, and a configured coding agent. See [runtime support](https://github.com/rwo572/productfoo/blob/main/docs/runtime-support.md) for tested versions.
+
+### 1. Install productfoo
+
+```bash
+npm install -g productfoo
+cd /path/to/your/project
+foo doctor
+```
+
+This installs the release tagged `latest` on npm. The package is `productfoo`. Terminal commands start with `foo`; agent commands use your runtime’s native syntax, such as `/foo:spec` in Claude Code. Local workflows need no productfoo account or hosted service.
+
+### 2. Set up your coding agent
+
+<details>
+<summary><strong>Claude Code, Cursor, Grok Bot, or OpenCode</strong></summary>
+
+Preview the project setup, review the proposed files, then apply it:
+
+```bash
+foo agent setup --agent all --scope project --dry-run
+foo agent setup --agent all --scope project --yes
+```
+
+To target one agent, replace `all` with `codex` (Codex), `claude-code` (Claude Code), `cursor` (Cursor), `grok` (Grok Bot), or `opencode` (OpenCode). For Codex, use `--scope global` as shown below.
+
+[Add productfoo to Grok Bot](https://x.ai/bot/6BQEkzxJ3C_UZHibSbM-G).
+
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+Preview and install the personal plugin:
+
+```bash
+foo agent setup --agent codex --scope global --dry-run
+foo agent setup --agent codex --scope global --yes
+```
+
+Start a new Codex task so it loads the commands.
+
+</details>
+
+See [agent setup](https://github.com/rwo572/productfoo/blob/main/docs/agent-adapters.md) for runtime-specific details.
+
+### 3. Give your agent a destination
+
+Ask your favorite coding agent to use productfoo to shape the work. In Claude Code:
+
+> /foo:spec Customers keep re-creating the same filters. Let's productize this.
+
+If you don’t know where to start, run `foo init`. It reads the project and suggests a low-stakes first move.
+
+## Why productfoo exists
+
+### The agent built the feature, but missed the point
+
+“Add saved filters” leaves a lot unsaid. Are filters personal or shared? Who can change them? What happens when the underlying data changes?
+
+`foo spec` helps resolve the questions that change the work. It records the problem, scope, decisions, and acceptance checks before the agent builds. The agent should inspect the project first and ask you only what the available evidence cannot answer.
+
+For deeper work, `spec-swarm` brings in relevant product, design, engineering, and other expert perspectives. `spec-cleanup` makes the resulting plan specific enough to implement.
+
+**Start with:** `foo spec "your feature"`
+
+### The agent ran with the first idea
+
+A detailed implementation can still solve the wrong problem. Before committing to a direction, you may need customer evidence, public research, or a better alternative.
+
+`foo discovery` turns approved customer calls into evidence you can review. `foo research` helps gather and document public research. `foo ideate` explores alternatives, and `foo pitch` builds the case for pursuing an opportunity, postponing it, or walking away.
+
+**Start with:** `foo ideate "the problem you want to solve"`
+
+### You only discover the wrong product after it is built
+
+It is easier to react to a concrete workflow than to imagine one from a spec.
+
+`foo preview` turns a spec into a reviewable artifact before implementation. `foo roast` challenges weak assumptions, unnecessary scope, and likely drift. Feedback becomes a proposed change to the agreement for you to accept.
+
+**Start with:** `foo preview specs/my-feature`
+
+### Every session needs the same explanation
+
+A conversation can hold a lot of context. The next agent may not have it.
+
+A productfoo Spec keeps the agreement in plain files:
+
+| File | What it keeps |
+|---|---|
+| `spec.md` | Intent, requirements, decisions, and open questions |
+| `tasks.yaml` | Work, acceptance checks, and task status |
+| `events.jsonl` | The record of what happened |
+
+The record distinguishes work you agreed to, ideas waiting for your decision, and necessary work discovered during implementation. Another agent can read it and continue from the recorded state.
+
+**Read:** [The productfoo Spec](https://github.com/rwo572/productfoo/blob/main/docs/foo-spec.md)
+
+### “Done” does not tell you what was verified
+
+Passing tests is useful evidence. You also need to know whether the result matches the work you agreed to do.
+
+`foo asp reconcile` compares implementation evidence with the spec and surfaces differences. A task marked complete without evidence stays **done, proof pending**. The checks, gaps, and decisions remain available for review.
+
+For autonomous work, `review-loop` evaluates whether the proposed process has a checkable goal, useful feedback, a stopping condition, and a handoff backed by evidence. Loop validation checks the declared contract and budget.
+
+**Start with:** `foo asp reconcile specs/my-feature --git-diff`
+
+## What this adds to a bare coding agent
+
+A capable coding agent can do this when prompted carefully. productfoo makes the discipline reusable, explicit, and inspectable so you don’t have to supply it every time.
+
+| | Bare coding agent | With productfoo |
+|---|---|---|
+| Starting point | Your prompt and repository context | An agreement on the problem, scope, and success criteria |
+| Product judgment | Depends on what you ask it to consider | Repeatable research, critique, and expert-review workflows |
+| Scope changes | Assumptions can accumulate as work proceeds | Changes are recorded and surfaced for decisions |
+| Completion | A summary of implementation and test results | Evidence compared with the agreed spec, including gaps |
+| Handoff | Context may need to be explained again | The agreement and progress live in repository files |
+
+For a typo or a small, well-defined fix, keep the process small. The structure matters most when work is ambiguous, spans sessions, or gives an agent meaningful autonomy.
+
+## Workflow reference
+
+These are terminal commands. You can also describe the work to your coding agent and ask it to use productfoo.
+
+```text
+BEFORE A SPEC EXISTS
+
+  Unfamiliar territory               foo research
+  PMs · designers · FDEs         ──▶ cited, untrusted findings   ──┐
+                                                                   │
+  Customer calls and feedback        foo discovery                 │
+  FDEs · PMs · CS                ──▶ themes you review           ──┤
+                                                                   │
+  A raw idea, many directions        foo ideate                    │
+  founders · PMs                 ──▶ stress-tested shortlist     ──┤
+                                                                   │
+  Should we build this at all?       foo pitch                     │
+  founders · product leads       ──▶ GO / NOT-NOW / NO-GO        ──┤
+                                                                   │
+  A clear feature request            foo spec                      │
+  engineers · everyone           ══▶ ~30 seconds to shape        ══╡
+                                                                   ▼
+                                                     ┌───────────────────────────┐
+                                                     │ productfoo Spec           │
+                                                     │ intent, decisions,        │
+                                                     │ tasks, proof              │
+                                                     │ [ you agree it ]          │
+                                                     └─────────────┬─────────────┘
+ONCE A SPEC EXISTS                                                 │
+                                                                   │
+  Is the scope tight?                foo roast                     │
+  senior engineers               ◀── cuts + candidate checks     ◀─┤
+                                                                   │
+  Will it look right?                foo preview                   │
+  designers · PMs                ◀── a reviewable artifact       ◀─┤
+                                                                   │
+  Did we ship what we agreed?        foo reconcile                 │
+  AI Ops · engineers             ◀── drift or proof              ◀─┘
+
+  Not sure which row you are in? foo init reads the project and suggests a first move.
+```
+
+| When you want to… | Use |
+|---|---|
+| Find a useful starting point | `foo init` |
+| Research an unfamiliar area | `foo research` |
+| Turn approved customer calls into evidence | `foo discovery` |
+| Explore and compare ideas | `foo ideate` |
+| Decide whether an opportunity is worth pursuing | `foo pitch` |
+| Agree on what to build | `foo spec` |
+| Challenge any spec or prototype | `foo roast` |
+| Preview the proposed product | `foo preview` |
+| Compare the implementation with an existing spec | `foo asp reconcile specs/my-feature --git-diff` |
+
+Run `foo help` for the main workflows or `foo help --all` for the complete command surface.
+
+### Skills worth knowing
+
+The agent uses these skills within the workflows. Read them, or ask your agent to use one for a specific task.
+
+- **[interview-me](https://github.com/rwo572/productfoo/blob/main/skills/interview-me/SKILL.md)**: Resolve the consequential questions before writing a spec.
+- **[spec-swarm](https://github.com/rwo572/productfoo/blob/main/skills/spec-swarm/SKILL.md)**: Challenge a plan through relevant expert perspectives.
+- **[spec-cleanup](https://github.com/rwo572/productfoo/blob/main/skills/spec-cleanup/SKILL.md)**: Make requirements, tasks, and checks ready for implementation.
+- **[foo-roast](https://github.com/rwo572/productfoo/blob/main/skills/foo-roast/SKILL.md)**: Find weak assumptions, cut unnecessary scope, and suggest useful checks.
+- **[preview-swarm](https://github.com/rwo572/productfoo/blob/main/skills/preview-swarm/SKILL.md)**: Build an artifact you can inspect before committing to implementation.
+- **[review-loop](https://github.com/rwo572/productfoo/blob/main/skills/review-loop/SKILL.md)**: Evaluate whether autonomous work can converge and finish with evidence.
+
+Browse the [skill registry](https://github.com/rwo572/productfoo/blob/main/skills/skill-registry.yaml) for the full inventory and each skill’s active or draft status.
+
+## Go deeper
+
+- [Getting started](https://github.com/rwo572/productfoo/blob/main/docs/getting-started.md): your first complete workflow.
+- [Firecrawl research](https://github.com/rwo572/productfoo/blob/main/docs/firecrawl.md): connect your own plugin or API key for public-web research. Firecrawl is optional and requires separate setup.
+- [Worked examples](https://github.com/rwo572/productfoo/blob/main/examples/): inspect sample specs and their acceptance checks.
+- [CLI reference](https://github.com/rwo572/productfoo/blob/main/docs/cli-reference.md): commands, flags, and output contracts.
+- [Development setup](https://github.com/rwo572/productfoo/blob/main/.github/CONTRIBUTING.md#development-setup): build and test productfoo from source.
+- [Documentation index](https://github.com/rwo572/productfoo/blob/main/docs/README.md): the complete documentation.
+
+## Project status and responsible use
+
+productfoo is a personal open-source project, shared for people who find it useful.
+It is under active experimentation; maintenance, compatibility, support, and
+security fixes are best effort, with no guaranteed response or release schedule.
+
+Its checks help you review agent work. They are not a sandbox and cannot guarantee
+correct output, prevent every unintended action, detect every secret, or ensure an
+agent follows instructions. Start in a disposable repository with synthetic data
+and limited permissions. Review generated changes and commands before accepting
+them, and keep backups of work you care about.
+
+The CLI's local workflows do not require a productfoo account or hosted service.
+Your coding agent, model provider, and connected tools may still send data outside
+your machine and incur charges under their own permissions and settings. Review
+those settings before providing private information or enabling external actions.
+
+This is a personal project, unaffiliated with and not endorsed by any current or
+former employer. It is provided under the warranty and liability terms in the
+[Apache License 2.0](https://github.com/rwo572/productfoo/blob/main/LICENSE).
+
+## Contributions and support
+
+Contributions are welcome. Please open an issue before starting substantial work
+so we can agree on direction. Keep pull requests focused and include relevant
+tests or verification.
+
+Rachel Wolan ([@rwo572](https://github.com/rwo572)) maintains productfoo, reviews
+contributions, and makes the final decision on scope and merging. Contribute
+through a fork and pull request; repository write access and merging remain with
+the maintainer. Submitting a contribution does not guarantee acceptance.
+
+Maintenance and support are best effort, with no guaranteed response or roadmap.
+
+- [Maintenance and contribution policy](https://github.com/rwo572/productfoo/blob/main/.github/CONTRIBUTING.md) —
+  review process and development setup.
+- [Code of Conduct](https://github.com/rwo572/productfoo/blob/main/.github/CODE_OF_CONDUCT.md).
+- [Security policy](https://github.com/rwo572/productfoo/blob/main/.github/SECURITY.md) —
+  report vulnerabilities privately; do not open a public issue.
+- [Changelog](https://github.com/rwo572/productfoo/blob/main/docs/CHANGELOG.md).
+- [Third-party notices](https://github.com/rwo572/productfoo/blob/main/docs/THIRD_PARTY_NOTICES.md).
+
+## Acknowledgments & inspiration
+
+productfoo draws on the work of people making product judgment and agent
+workflows more useful. Thank you to:
+
+- **[Matt Pocock](https://github.com/mattpocock/skills)** for `grill-me` and its
+  approach to pressure-testing plans: ask focused questions, work through the
+  decisions, and inspect the code before asking the human. His skills README
+  also inspired this README’s setup-first, problem-led organization.
+- **[Paul Bakaus and Impeccable](https://github.com/pbakaus/impeccable)** for
+  design critique, accessibility review, and visual craft in agent workflows.
+- **[Lenny Rachitsky and Lenny’s Podcast guests](https://www.lennysnewsletter.com/)**
+  for the product judgment, growth, strategy, taste, and AI-product thinking
+  referenced throughout the expert lenses. Individual frameworks and ideas
+  remain attributed to their original speakers in the relevant skills.
+- **[Thariq Shihipar](https://thariqs.github.io/html-effectiveness/)** for
+  “The unreasonable effectiveness of HTML” and its examples of interactive,
+  reviewable agent output, which informed the build-preview patterns.
+- **[Anthropic’s frontend-design skill](https://github.com/anthropics/skills/tree/main/skills/frontend-design)**
+  for guidance on distinctive, intentional frontend design with coding agents.
+- **[Matt Van Horn’s last30days](https://github.com/mvanhorn/last30days-skill)**
+  for inspiration around researching recent conversations and synthesizing
+  grounded findings.
+
+These acknowledgments describe influences and companion tools. Runtime
+third-party dependencies are documented in
+[Third-party notices](https://github.com/rwo572/productfoo/blob/main/docs/THIRD_PARTY_NOTICES.md).
+
+## License
+
+productfoo is released under the [Apache License 2.0](https://github.com/rwo572/productfoo/blob/main/LICENSE).

package/bin/foo

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Source-checkout convenience entrypoint; the npm executable uses foo.mjs.
+import "./foo.mjs";

package/bin/foo.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// Repository checkouts run their built CLI from dist/. Packed installations
+// ship dist-public/. Private operator output is never a launcher candidate.
+const here = path.dirname(fileURLToPath(import.meta.url));
+const candidates = [
+  path.join(here, "..", "dist", "src", "cli.js"),
+  path.join(here, "..", "dist-public", "src", "cli.js"),
+];
+const cliPath = candidates.find((candidate) => existsSync(candidate));
+
+if (!cliPath) {
+  process.stderr.write(
+    "foo: CLI build not found (dist/src/cli.js or dist-public/src/cli.js).\n" +
+      "This checkout has no built CLI. From the repo root run:\n" +
+      "  npm ci && npm run build\n",
+  );
+  process.exit(1);
+}
+
+import(pathToFileURL(cliPath).href)
+  .then(({ main }) => main(process.argv.slice(2)))
+  .then((exitCode) => {
+    process.exitCode = exitCode;
+  })
+  .catch((error) => {
+    const message = error?.message ?? String(error);
+    if (error?.code === "ERR_MODULE_NOT_FOUND" || /Cannot find package/.test(message)) {
+      // Explain dependency repair without exposing an import stack trace.
+      process.stderr.write(
+        "foo: a runtime dependency is missing (node_modules).\n" +
+          "For a source checkout, run npm ci && npm run build.\n" +
+          "For an installed package, reinstall the reviewed tarball.\n",
+      );
+    } else {
+      process.stderr.write(`foo: failed to start CLI: ${message}\n`);
+    }
+    process.exit(1);
+  });

package/commands/bug.md

@@ -0,0 +1,31 @@
+---
+description: Report something in foo that broke or behaved incorrectly
+argument-hint: [what happened]
+---
+
+<!-- foo-managed-command: bug v0 -->
+
+productfoo's **bug** command is a thin adapter over the canonical one-capsule report
+flow. It adds no separate persistence, scrubbing, networking, tracker, or
+repair behavior; `foo report add` remains the only collection implementation.
+
+## What the harness ships
+
+A thin launcher, and nothing more: ask for missing expected and actual behavior
+one question at a time. In an agent runtime, pass those answers as the exact
+`--expected` and `--actual` argument values, add `--reproduction` only when it
+was provided, and request `--json`. At a human TTY, bare `foo report add` may
+collect the fields interactively. Never interpolate user text into a shell
+command.
+
+## Operating contract
+
+1. Use `foo report add`, `foo report show <capsule-id> --json`, and `foo report delete <capsule-id> --approve <payload-digest> --json` for local reports.
+2. Reports stay on this machine. Obtain fresh approval for the reviewed ID+digest before local deletion. Sending is unavailable; never offer uploads.
+3. Saved reports are local diagnostics; old receipts are historical. Do not promise triage, a fix, an Issue URL, or start a repair agent.
+
+Every foo command also carries:
+
+- productfoo-first: for product, spec, packet, planning, decision, correction, validation, or drift work, reach for foo before generic planning — `foo spec` or `foo spec start` for unresolved intent, `foo asp validate|reconcile|event|task` for packet-tied work. Compound Engineering, Superpowers, and generic planners are downstream companions, never the first move.
+- Load skills with `foo skill <name>`; productfoo loads verified bundled skills or an explicitly approved development tree, and always refuses caller-repository shadowing. If `foo doctor` reports delivery unavailable, run `foo init` or update productfoo; never bypass trust checks.
+- Keep productfoo's judgment ledger in what you show: claim, evidence, confidence, dissent, and the decisions that are the user's alone.