Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
187 lines (147 loc) · 8.58 KB

CONTRIBUTING.md

File metadata and controls

187 lines (147 loc) · 8.58 KB
Raw

Contributing to Pantheon

Pantheon is a working prototype (see the README's "Known gaps" section), so expect some rough edges. Contributions, bug reports, and design feedback are welcome.

Prerequisites

Pantheon runs on Windows and Linux. The terminal layer is portable-pty: ConPTY on Windows, a Unix PTY elsewhere. On both platforms you will need:

On Windows, also install the Tauri CLI prerequisites, including the Visual Studio 2022 Build Tools. dev.cmd and build.cmd both call vcvars64.bat for you, so a plain cargo build from a regular shell will not link correctly; use the provided scripts.

On Linux, install the GTK and WebKitGTK development packages. On Ubuntu 26.04:

sudo apt install pkg-config libwebkit2gtk-4.1-dev libgtk-3-dev \
  librsvg2-dev libssl-dev libdbus-1-dev

There is no environment setup step on Linux, so cargo build works from any shell; dev.sh and build.sh are thin wrappers kept for parity.

Setup

pnpm install
.\dev.cmd        # Windows: sets up the MSVC environment, then `pnpm tauri dev`
pnpm install
./dev.sh         # Linux

Building

Run .\build.cmd on Windows or ./build.sh on Linux. Artifacts land in src-tauri/target/release/: pantheon.exe plus the NSIS installer under bundle/nsis/ on Windows, and pantheon plus bundle/deb/ and bundle/appimage/ on Linux.

Testing

cd src-tauri
cargo test

This covers the PTY submit-timing logic and the shared-brain prompt formatting. Frontend coverage is thin, so a change to src/ should also be exercised manually with dev.cmd or dev.sh and checked with:

pnpm build   # runs `tsc` in strict mode, then the Vite build
pnpm test    # Vitest

Branching and commits

Branch off main with a short, descriptive name in the style already used in this repo, for example fix/dispatch-submit-race or feat/task-board. Commit messages are sentence-style and imperative ("Wait for a quiet target before submitting a dispatch"), not Conventional Commits prefixes. Keep commits scoped to one change so the history stays readable.

Review before you commit

If a change was made with the help of a Pantheon session, or any AI coding agent, it needs a second pair of eyes from a different model before it lands, not a rubber stamp from the model that wrote it. The workflow:

  1. Implement. One session (the implementer) makes the change and gets it working: tests passing, pnpm build clean, no unrelated files touched.
  2. Route to a different-model reviewer. Hand the diff to a session running a different model than the implementer, for example Claude Code implemented and Codex or opencode reviews. If Pantheon is not available, any second reviewer works, but the model actually has to differ, not just be a fresh prompt to the same one.
  3. Reviewer reports findings. The reviewer reads the diff against the original request, not just the code in isolation, and returns concrete findings: correctness, scope creep, security-relevant paths, missing tests.
  4. Implementer fixes and asks for a recheck. Do not self-certify a fix; send it back to the same reviewer for a second pass on just the delta.
  5. Reviewer approves. Only once the reviewer has no more findings, or the remaining ones are explicitly accepted and noted in the PR, does the change move to commit.
  6. Commit and push. Fill in the PR checklist below with what the review actually found.

This exists to catch what a single model misses about its own output, not to slow down every one-line fix. Use judgment: a typo in a comment does not need a cross-model review. A change to mcp.rs, worktree.rs, session identity, dispatch, or anything else in SECURITY.md's scope always does.

Pull requests

Never commit to main. Every change lands on its own branch and through a pull request, whatever its size: a bug fix, a feature, a doc correction. Branch before editing, named for the work (fix/dispatch-drops-leading-chunks), and keep one branch to one coherent change. When a branch has grown past what a reviewer can hold in their head, split it rather than letting it accumulate.

This project explicitly requires a pull request, so opening one is part of finishing the work rather than something to ask about first.

Propose the work when it is done, not when someone notices. On 2026-08-13 this repository had 16 commits sitting on one branch with no PR, including the dispatch truncation fix, on a branch whose name had stopped describing its contents. Nothing was lost, but the work was invisible to everyone except the session that wrote it, and by then it was too large to review in one sitting.

Open a PR against main using the PR template; it captures the checklist below. Describe what changed and why, and call out anything that touches the areas covered in SECURITY.md (the MCP server, worktree isolation, or process spawning) so it gets a closer look. Please run cargo test and pnpm build locally before requesting review. CI repeats those checks and runs dependency, secret, and static-analysis scanners on pull requests.

PR checklist

  • Implementer: model and session (for example, Claude Code, sess-2).
  • Reviewer: model and session, different from the implementer.
  • Review result: approved, or approved with noted exceptions listed.
  • Tests: cargo test and pnpm build both run locally, with pass or fail noted.
  • Security impact: none, or a short description if the change touches the MCP server, worktree isolation, process spawning, or IPC.
  • Confirmation that this diff contains only the intended change, with no unrelated files or another session's untracked or uncommitted work pulled in.

Filing a work item

The Work item issue form (.github/ISSUE_TEMPLATE/work-item.yml) asks for seven short sections: What, Why, Scope, ### Done when, Validation, Dependencies and decisions, and Links, all required. The form is copied verbatim from Lexicon's integration-library/github-tracking/ (README.md, body-contract.md), which is the source of the contract and stays authoritative for it. Start from the Markdown scaffold and use its companion authoring checker. These links pin the adopted version. Use a Lexicon checkout containing that revision or a later version of the same contract; the integration folder links to maintained sources.

Filing through the browser uses the form directly. Filing through gh issue create --body-file (or gh issue edit --body-file) has to reproduce the same seven headings by hand, using integration-library/github-tracking/templates/work-item-body.md in a Lexicon checkout as the scaffold. Before running gh issue create or gh issue edit, validate the body structurally:

LEXICON_CHECKOUT=/path/to/lexicon
python "$LEXICON_CHECKOUT/integration-library/github-tracking/work_item_check.py" \
  --body-file /tmp/issue-body.md

That check confirms the seven headings are present and not left as placeholder text; it cannot judge whether the content is adequate, which is what review is still for.

This form carries no Priority or Status field. The staged handoff in docs/github-issues.md defines which tracker is authoritative: .tasks/ stays authoritative until verified activation, then remains a read-only historical ledger while GitHub Issues owns deliverables and the repository's selected GitHub Project owns stage and priority. No Project stage or priority mirror belongs in the issue body.

Code style

  • Rust: no repo-wide rustfmt.toml or clippy.toml yet; match the style of the file you are editing and run cargo fmt before committing.
  • TypeScript: tsconfig.json has strict on with noUnusedLocals and noUnusedParameters; pnpm build will fail on either. There is no ESLint or Prettier config in the repo yet, so again, match the surrounding file.

Scope note

ui-gallery/ holds standalone HTML design explorations, not part of the build. It is a useful reference for planned UI (see the README's "Known gaps" and IMPROVEMENT-AUDIT.md) but changes there do not affect the app.