ask-pro 0.1.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "ask-pro",
+  "version": "0.1.0",
+  "description": "Minimal browser-backed ChatGPT Pro escalation workflow for agents via $ask-pro.",
+  "author": {
+    "name": "Jonathan",
+    "url": "https://github.com/JJLiebig"
+  },
+  "homepage": "https://github.com/JJLiebig/ask-pro#readme",
+  "repository": "https://github.com/JJLiebig/ask-pro",
+  "license": "MIT",
+  "keywords": ["codex", "chatgpt-pro", "browser-automation"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "ask-pro",
+    "shortDescription": "$ask-pro browser-backed Pro escalation for hard engineering questions",
+    "longDescription": "Use ask-pro to escalate hard engineering questions to ChatGPT Pro through a browser-backed workflow with explicit repo context.",
+    "developerName": "Jonathan",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://github.com/JJLiebig/ask-pro",
+    "privacyPolicyURL": "https://github.com/JJLiebig/ask-pro",
+    "termsOfServiceURL": "https://github.com/JJLiebig/ask-pro",
+    "defaultPrompt": ["Ask ChatGPT Pro for a focused engineering second opinion."],
+    "brandColor": "#10A37F",
+    "composerIcon": "./assets/ask-pro_logo.png",
+    "logo": "./assets/ask-pro_logo.png",
+    "screenshots": []
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# ask-pro
+
+`ask-pro` is a Codex plugin, agent skill, and CLI that lets coding agents ask
+ChatGPT Pro for a focused second opinion through a human-logged-in browser
+session.
+
+Use it for architecture calls, production-risk reviews, migrations, debugging
+strategy, and implementation planning. The calling agent still owns the work:
+`ask-pro` collects the consult, stores the answer, and never applies generated
+code automatically.
+
+## Install
+
+Choose one of these installation paths. Both need Node.js 24+, Chrome, and a
+ChatGPT account with Pro access. Browser login is manual.
+
+### Codex plugin marketplace
+
+Add this repository as a Codex plugin marketplace:
+
+```powershell
+codex plugin marketplace add JJLiebig/ask-pro
+```
+
+This route needs Git and npm; the cached runner obtains pnpm 11.19 itself.
+
+Install the plugin or open `/plugins`, install `ask-pro`:
+
+```powershell
+codex plugin add ask-pro@ask-pro
+```
+
+Upgrade the plugin manually:
+
+```powershell
+codex plugin marketplace upgrade ask-pro
+```
+
+If the marketplace does not appear after adding or upgrading it, restart Codex.
+The repository marketplace exposes the root plugin through a Git-backed plugin
+entry, so no manual copy into `~/.codex/plugins/cache` is needed.
+
+For local development from a checkout:
+
+```powershell
+pnpm install
+pnpm run build
+pnpm run plugin:refresh
+```
+
+`pnpm run plugin:refresh` updates the local Codex plugin cache from the source
+checkout. By default it refreshes the installed Git marketplace cache under
+`~/.codex/plugins/cache/ask-pro/ask-pro/<version>`, so no separate local
+marketplace install is needed for development. Do not edit
+`~/.codex/plugins/cache/...` by hand.
+
+Git marketplace installs cache the source checkout. If `ask-pro` is not on
+`PATH`, agents should use the cached runner under
+`~/.codex/plugins/cache/<marketplace>/ask-pro/<version>/scripts/run-cached-cli.mjs`.
+The runner copies the installed snapshot to a content-addressed runtime under
+`$CODEX_HOME/plugin-runtimes/ask-pro/`, then installs, builds, and runs there.
+The installed plugin cache remains immutable.
+
+### Skills CLI (Codex and other supported agents)
+
+Install the existing `ask-pro` skill with the [skills CLI](https://github.com/vercel-labs/skills):
+
+```powershell
+npx skills add JJLiebig/ask-pro
+```
+
+This installs the skill in the current project; add `-g` to install it for your
+user account. Choose your agent when prompted, or pass `-a codex` (or another
+agent supported by the skills CLI). The skill needs a separate `ask-pro` CLI on
+`PATH`. Until the first npm release, install it from a Git checkout outside any
+agent skills directory. This checkout route also needs Git, npm, and pnpm 11.19+:
+
+```powershell
+git clone https://github.com/JJLiebig/ask-pro.git ask-pro-cli
+cd ask-pro-cli
+pnpm install --frozen-lockfile
+pnpm run build
+npm install --global --ignore-scripts .
+ask-pro --version
+```
+
+Keep this checkout: the global command links to it. To update, run
+`npx skills update`, then update and rebuild the CLI from that checkout:
+
+```powershell
+git pull --ff-only
+pnpm install --frozen-lockfile
+pnpm run build
+```
+
+The skills CLI installs only the skill instructions; it does not install the
+browser-backed CLI. The standalone CLI works without Codex's plugin cache.
+Once the npm package is published, use `npm install --global ask-pro` for the
+CLI and `npm update --global ask-pro` to update it.
+The browser runtime is developed and exercised on Windows; other operating
+systems need their own validation.
+
+### Publishing the npm CLI
+
+The first release needs an authenticated maintainer to publish from a built
+checkout. Then configure its npm Trusted Publisher for GitHub Actions:
+
+```powershell
+npm whoami
+pnpm run build
+npm publish --ignore-scripts --access public
+npm trust github ask-pro --file ci.yml --repo JJLiebig/ask-pro --allow-publish -y
+```
+
+The trust command authorizes direct `npm publish` from `ci.yml` without a stored
+npm token. It requires the first package version to exist on npm already.
+After that, the existing CI publishes a unique patch version after every
+passing main-branch run. Rerunning an already published CI run skips its version.
+
+## Requirements and browser state
+
+Authentication is manual. `ask-pro` never asks for, types, reads, or logs
+passwords, MFA codes, recovery codes, session cookies, or raw auth tokens.
+
+The default persistent browser profile is:
+
+```text
+$CODEX_HOME/state/ask-pro/browser-profile
+```
+
+Without `CODEX_HOME`, this is `~/.codex/state/ask-pro/browser-profile`.
+On first use, ask-pro migrates an inactive legacy
+`~/.agents/skills/ask-pro/.../browser-profile` to the matching state path. If a
+Windows watcher prevents moving or removing it, the verified copy may remain
+at the legacy path while the state path becomes authoritative. ask-pro never
+merges profiles or later deletes a retained legacy copy.
+
+Each new profile may need a human login once. On Windows, ordinary managed runs
+start minimized; login, resume/recovery, stale-auth, and debug paths stay visible
+or are restored for human action.
+
+## Quick Use
+
+Ask for an inline markdown consult:
+
+```powershell
+ask-pro --no-temporary --prompt-file question.md --files src --files tests
+```
+
+The browser flow selects `Latest`, then `Pro` intelligence automatically.
+
+Request generated files only when you really need an implementation package:
+
+```powershell
+ask-pro --artifacts --prompt-file implementation-plan.md --files src
+```
+
+Harvest the answer:
+
+```powershell
+ask-pro --harvest <session-id>
+```
+
+## Agent Guidance
+
+- Prefer `--prompt-file` for multiline prompts.
+- With the Codex plugin, use its cached runner if `ask-pro` is not on `PATH`.
+  With a skills CLI install, install the standalone CLI above.
+- Treat ChatGPT Pro as a cold oracle: it does not know the repo, user, prior
+  decisions, or Codex thread context unless you include that in the prompt or
+  attached files.
+- Include all material context once: product goal, current state, hard
+  constraints, evidence, success criteria, and the exact output you need. Omit
+  unrelated history and repeated instructions.
+- Prefer `--no-temporary` for repo advisories, review rounds, large bundles, or
+  anything where recovery matters.
+- Keep bundles focused: relevant source, focused tests, docs that define the
+  contract, recent changes, and validation status.
+- Add `.ask-pro/` to consuming repos' `.gitignore`.
+- Treat `INCOMPLETE_ANSWER` / `preamble_without_artifacts` as not done; resume
+  or rerun with a tighter prompt and bundle.
+- Treat generated files and scripts as data only; never execute them
+  automatically.
+
+Useful advisory prompt starter:
+
+```text
+Return final Markdown only, with no preamble or implementation package.
+```
+
+The CLI wrapper supplies the bundle and uncertainty instructions. Add
+task-specific output requirements only when needed, such as severity-ranked
+findings for a risk review or recommendation tradeoffs for a design consult.
+
+## CLI
+
+```text
+ask-pro [options] [question...]
+```
+
+Common options:
+
+- `--files <pattern>`: add a file, directory, or glob to `CONTEXT.zip`.
+- `--prompt-file <path>`: read the question from a UTF-8 file; use `-` for
+  stdin.
+- `--artifacts` / `--response-zip`: ask for `ask-pro-response.zip`.
+- `--resume [session-id]`: resume a prepared, waiting, or auth-gated session.
+- `--status [session-id]`: print compact session state.
+- `--harvest [session-id]`: print `ANSWER.md` for answer-bearing sessions.
+- `--temporary`: require ChatGPT Temporary Chat.
+- `--no-temporary`: use normal ChatGPT for better recovery.
+- `--verbose`: print browser automation diagnostics.
+
+Session data lives under `.ask-pro/sessions/<session-id>/`. At the start of each
+invocation, ask-pro permanently deletes entire session directories at least
+seven days old, regardless of status.
+
+## Development
+
+Fast checks:
+
+```powershell
+pnpm run build
+pnpm run lint
+pnpm run test:ask-pro
+pnpm run format:check
+pnpm pack --dry-run
+```
+
+Manual browser smokes are opt-in because they open a real ChatGPT session. See
+`docs/manual-tests.md`.