@yahyahammad/venastine 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +14 -0
- package/LICENSE +201 -0
- package/NOTICE +14 -0
- package/PRIVACY.md +66 -0
- package/README.md +878 -0
- package/SECURITY.md +88 -0
- package/THIRD_PARTY_NOTICES.md +100 -0
- package/agents/builtin/compactor.md +75 -0
- package/agents/builtin/explore.md +77 -0
- package/agents/builtin/grill-me.md +27 -0
- package/agents/builtin/initializer.md +94 -0
- package/agents/builtin/pipeline-reviewer.md +100 -0
- package/agents/builtin/plan.md +88 -0
- package/agents/builtin/review.md +74 -0
- package/agents/manager.py +195 -0
- package/agents/subagent_tool.py +215 -0
- package/agents/tui_commands.py +136 -0
- package/bin/venastine.mjs +382 -0
- package/config.py +1198 -0
- package/core/__init__.py +0 -0
- package/core/approval.py +115 -0
- package/core/client.py +1548 -0
- package/core/compaction.py +959 -0
- package/core/config_loader.py +1563 -0
- package/core/events.py +61 -0
- package/core/interaction.py +328 -0
- package/core/loop.py +1353 -0
- package/core/memory.py +370 -0
- package/core/model_windows.py +175 -0
- package/core/pipeline_models.py +176 -0
- package/core/reasoning/__init__.py +0 -0
- package/core/reasoning/authorization.py +130 -0
- package/core/reasoning/base.py +219 -0
- package/core/reasoning/confidence_scoring.py +468 -0
- package/core/reasoning/events.py +149 -0
- package/core/reasoning/json_retry.py +219 -0
- package/core/reasoning/orchestrator.py +1382 -0
- package/core/reasoning/output_writer.py +286 -0
- package/core/reasoning/payload_validation.py +398 -0
- package/core/reasoning/pipeline_storage.py +361 -0
- package/core/reasoning/review.py +615 -0
- package/core/reasoning/scholar.py +434 -0
- package/core/reasoning/source_corpus.py +327 -0
- package/core/reasoning/source_scoring.py +855 -0
- package/core/replay.py +167 -0
- package/core/session.py +153 -0
- package/core/workspace_trust.py +207 -0
- package/credentials.py +180 -0
- package/database.py +252 -0
- package/env_secrets.py +77 -0
- package/json_store.py +123 -0
- package/logging_setup.py +185 -0
- package/main.py +1959 -0
- package/mcp_client/__init__.py +15 -0
- package/mcp_client/client.py +499 -0
- package/mcp_client/config.py +379 -0
- package/mcp_client/registration.py +182 -0
- package/memories/manager.py +132 -0
- package/memories/tui_commands.py +232 -0
- package/package.json +73 -0
- package/project_init/config_files.py +278 -0
- package/project_init/doc_sets.py +330 -0
- package/project_init/generator.py +564 -0
- package/project_init/manifest.py +406 -0
- package/project_init/tui_commands.py +144 -0
- package/prompts/__init__.py +0 -0
- package/prompts/annotate.md +14 -0
- package/prompts/assumption_audit.md +27 -0
- package/prompts/claim_extraction.md +34 -0
- package/prompts/completeness.md +18 -0
- package/prompts/confidence_tiers.md +23 -0
- package/prompts/critic_pass.md +24 -0
- package/prompts/final_synthesis.md +13 -0
- package/prompts/initial_generation.md +14 -0
- package/prompts/preliminary_plan.md +23 -0
- package/prompts/revalidate.md +25 -0
- package/prompts/revise.md +15 -0
- package/prompts/source_grounding.md +66 -0
- package/prompts/system_prompts.py +262 -0
- package/prompts/universal_system_prompt +7 -0
- package/prompts/untrusted_content +1 -0
- package/providers.json.example +92 -0
- package/pyproject.toml +100 -0
- package/requirements.txt +72 -0
- package/safety/__init__.py +0 -0
- package/safety/policy_enforcement.py +682 -0
- package/security/__init__.py +0 -0
- package/security/capability.py +177 -0
- package/security/permissions.py +190 -0
- package/security/posture.py +302 -0
- package/security/protected_paths.py +309 -0
- package/security/sandbox.py +985 -0
- package/skills/builtin/crypto/cryptography-verification.md +66 -0
- package/skills/builtin/math/formal-specification.md +67 -0
- package/skills/builtin/math/numerical-methods.md +66 -0
- package/skills/builtin/math/proof-writing.md +61 -0
- package/skills/builtin/research/experiment-design.md +62 -0
- package/skills/builtin/research/literature-review.md +65 -0
- package/skills/builtin/research/reproducibility.md +55 -0
- package/skills/builtin/research/source-evaluation.md +70 -0
- package/skills/builtin/research/statistical-inference.md +63 -0
- package/skills/builtin/research/technical-writing.md +59 -0
- package/skills/builtin/security/cybersecurity-research.md +63 -0
- package/skills/builtin/software/code-review.md +61 -0
- package/skills/builtin/software/debugging.md +61 -0
- package/skills/builtin/software/test-design.md +67 -0
- package/skills/manager.py +138 -0
- package/skills/tui_commands.py +111 -0
- package/storage.py +1005 -0
- package/tools/base.py +305 -0
- package/tools/builtin/__init__.py +0 -0
- package/tools/builtin/_math_common.py +377 -0
- package/tools/builtin/_net_common.py +61 -0
- package/tools/builtin/arxiv.py +223 -0
- package/tools/builtin/ask_user.py +213 -0
- package/tools/builtin/discrete_math.py +134 -0
- package/tools/builtin/fetch_url.py +153 -0
- package/tools/builtin/file_ops.py +412 -0
- package/tools/builtin/geometry.py +148 -0
- package/tools/builtin/get_time.py +20 -0
- package/tools/builtin/linear_algebra.py +155 -0
- package/tools/builtin/load_skill.py +66 -0
- package/tools/builtin/logic.py +96 -0
- package/tools/builtin/pin.py +193 -0
- package/tools/builtin/probability_stats.py +228 -0
- package/tools/builtin/project_docs.py +405 -0
- package/tools/builtin/remember.py +158 -0
- package/tools/builtin/shell.py +461 -0
- package/tools/builtin/symbolic_math.py +119 -0
- package/tools/builtin/todo.py +147 -0
- package/tools/builtin/web_search.py +151 -0
- package/tools/context.py +136 -0
- package/tools/isolation.py +314 -0
- package/tools/registry.py +897 -0
- package/tui/app.py +3423 -0
- package/tui/app.tcss +458 -0
- package/tui/commands.py +61 -0
- package/tui/diffs.py +265 -0
- package/tui/preferences.py +182 -0
- package/tui/ravens.py +146 -0
- package/tui/screens.py +943 -0
- package/tui/themes.py +366 -0
- package/tui/widgets.py +1239 -0
package/SECURITY.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Supported Versions
|
|
4
|
+
|
|
5
|
+
| Version | Supported |
|
|
6
|
+
|---|---|
|
|
7
|
+
| `main` (0.1.x) | Yes — security fixes ship on `main` first |
|
|
8
|
+
|
|
9
|
+
No long-term support branches yet. If you are on a fork, rebase on `main` before reporting.
|
|
10
|
+
|
|
11
|
+
## Reporting a Vulnerability
|
|
12
|
+
|
|
13
|
+
**Do not open a public issue, discussion, or pull request for a security vulnerability.**
|
|
14
|
+
|
|
15
|
+
**Email the maintainer at YahyaHammad@proton.me**, with the subject `[SECURITY] Venastine — <title>`.
|
|
16
|
+
|
|
17
|
+
Send a high-level summary first. Do not include full exploit code in plaintext until a secure transfer method has been agreed.
|
|
18
|
+
|
|
19
|
+
**Or use GitHub Private Vulnerability Reporting, where it is enabled:** *Security* tab → *Report a vulnerability*. It is the better channel when available, because the report, the fix and the advisory stay in one place — but it is a public-repository feature, so email is the channel that always works. Use email if you do not see the button.
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
### What to include
|
|
23
|
+
|
|
24
|
+
* Affected file(s) and line(s) — e.g. `security/sandbox.py:134`, `tools/registry.py:187`
|
|
25
|
+
* The concrete trigger — not "could be a problem" — the exact call, config (`ToolPermissions.shell=True`, `providers.json` entry), and filesystem/network/model state that reaches it
|
|
26
|
+
* Whether you can reproduce it offline (`python -m pytest -q` or a minimal script) and the commit you tested against
|
|
27
|
+
* Impact — what an attacker gains (exfiltration, code execution, bypass of approval, etc.) and whether it needs a local `shell` opt-in or is reachable on a default install
|
|
28
|
+
|
|
29
|
+
A minimal reproduction is not required, but it makes triage much faster.
|
|
30
|
+
|
|
31
|
+
## What to expect
|
|
32
|
+
|
|
33
|
+
* **Acknowledgment** within **2 business days**.
|
|
34
|
+
* **Triage and initial assessment** within **7 days** — we will confirm severity (`S1`–`S4` per `#15` tracker), whether it is in scope, and whether we need more info.
|
|
35
|
+
* **Fix and disclosure** under **coordinated disclosure with a 90-day window**:
|
|
36
|
+
* We will develop and test a fix on a private branch.
|
|
37
|
+
* We will ship the fix to `main` and tag a release as soon as it is ready — often well before day 90.
|
|
38
|
+
* Public disclosure (advisory + `DEVLOG.md` entry + `tests/BREAKING_CHANGES.md` row) happens **7 days after a fix ships to main** (to allow users time to update), or **90 days after your initial report**, whichever comes first, unless extended by mutual agreement.
|
|
39
|
+
* If you prefer, you will be credited in the advisory and `DEVLOG.md`; if not, you will remain anonymous.
|
|
40
|
+
|
|
41
|
+
We will keep the private thread updated at least every 14 days until resolution.
|
|
42
|
+
|
|
43
|
+
## Scope
|
|
44
|
+
|
|
45
|
+
In scope (examples):
|
|
46
|
+
|
|
47
|
+
* Bypass of `security/permissions.py` / `safety/policy_enforcement.py` (approval, `is_tool_allowed`, `requires_approval`, `check_output_policy`, blocked domains, secret redaction)
|
|
48
|
+
* Sandbox escape or network egress from a tier that should not have it (`security/sandbox.py`, `security/capability.py`)
|
|
49
|
+
* Workspace trust boundary bypass (`core/workspace_trust.py`, `core/config_loader.py` tier precedence)
|
|
50
|
+
* Credential exfiltration via tool arguments/results, logs, or `param_digest` display
|
|
51
|
+
* MCP `autoApprove` / `mcp.json` trust bypass
|
|
52
|
+
|
|
53
|
+
Out of scope: social engineering, physical access, compromise of a provider's own API, vulnerabilities in upstream dependencies without a harness-specific trigger, or issues that require `ToolPermissions.shell=True` together with `config.SHELL_APPROVAL_MODE = "never"` *and* are already documented as deliberate. `README.md` § *"`shell` is classified, not just approved"* records that `never` "is the old unbounded behaviour, kept on purpose" — in that mode `cat ~/.aws/credentials` runs on the host unprompted, and reaching it takes writing the word `never` in `config.py`. We still want such a report, but it will be closed as documented risk.
|
|
54
|
+
|
|
55
|
+
The same applies to `ALLOW_INSECURE_SANDBOX_FALLBACK = True` **together with** `AUTO_APPROVE_SANDBOX_FALLBACK = True`. That pair is unprompted arbitrary code on the host, with your own file access, including writes into the harness's own source tree — and the harness ships as a folder of Python, so a run can edit the code the next run executes. It is not defended against, and the reason is that it cannot be: an uncontained host shell cannot be bounded from inside the same process. A path check stops `echo x > ../config.py` and a `python -c` payload walks straight past it, which is a control that reads as safety without being it. Docker is the boundary. `README.md` § *"`shell` is classified, not just approved"* states the same thing at the point of use.
|
|
56
|
+
|
|
57
|
+
**Since batch 40 these settings are read ONCE, at startup, into a frozen posture
|
|
58
|
+
(`security/posture.py`).** Before that they were read live at every decision, so
|
|
59
|
+
`config.SHELL_APPROVAL_MODE = "never"` -- a single attribute assignment -- turned the shell gate off
|
|
60
|
+
for the rest of the process from anywhere in it, and `os.environ["VENASTINE_REDACT_OFF"] = "1"` did
|
|
61
|
+
the same for credential redaction. The posture now cannot be changed by a tool call, a settings
|
|
62
|
+
file, an environment variable, model output, or a TUI command; each of those is pinned by a test in
|
|
63
|
+
`tests/test_posture.py`.
|
|
64
|
+
|
|
65
|
+
It **can** be changed by arbitrary in-process Python, which can also rebind the accessor itself. A
|
|
66
|
+
frozen dataclass raises where a bare assignment succeeded, which raises the bar without closing the
|
|
67
|
+
class. In scope: any route from model output or repository content to a changed posture. Out of
|
|
68
|
+
scope: "I achieved arbitrary code execution and then changed it", which is a report about the
|
|
69
|
+
execution.
|
|
70
|
+
|
|
71
|
+
Note that all of these settings live in `config.py` (`SHELL_APPROVAL_MODE` at `config.py:245`, `ToolPermissions` at `config.py:640`, the two fallback flags at `config.py:221-222`) — none has a `settings.json` key or an environment override, by design. What IS in scope, and was fixed rather than documented: a sandboxed command reaching the harness's install tree or `~/.config/venastine/` through the workspace mount (`security/protected_paths.py`), and any argument spelling that makes the classifier and the executor disagree about where a token ends.
|
|
72
|
+
|
|
73
|
+
**The project's `.venastine/` directory is guarded by `PROTECTED_SEGMENTS` (`security/protected_paths.py`), one list with three consumers.** The `read`/`write`/`edit` tools hard-refuse any path resolving into the segment — pre-approval via `refusal_check` and again in the handlers, whatever the approval booleans and the workspace boundary say. A shell command whose tokens name the segment always requires approval under `tiered` mode, before the fallback opt-in and the capability rule can answer for it; when approved it still runs contained, where the read-only bind of `.venastine/` (§28 G6) is the write backstop. What remains documented risk: the shell check is a token check and does not parse (G2), so a spelling carrying no literal segment — a glob prefix like `.ven*/settings.json`, or a variable assigned outside the checked tokens — is not caught by it; on the auto-approved INERT tier that cannot matter, because EP5 executes argv with no shell and the tokens are the arguments, and every tier that could expand one is asked about anyway. `SHELL_APPROVAL_MODE = "never"` remains the opt-out it always was, and MCP servers exposing their own file tools are a separate surface this list does not reach.
|
|
74
|
+
|
|
75
|
+
## No bounty
|
|
76
|
+
|
|
77
|
+
This is an independent research project with no funding — **we cannot offer monetary rewards, bounties, or swag.** We will credit you publicly if you want, and we will prioritize a fix. If you need a bounty, please use a third-party program that covers this repo, or treat the report as a voluntary disclosure.
|
|
78
|
+
|
|
79
|
+
## Disclosure and credit
|
|
80
|
+
|
|
81
|
+
* We will publish a GitHub Security Advisory (GHSA) 7 days after the fix ships to main (or at the 90-day mark), requesting a CVE if the severity warrants it.
|
|
82
|
+
* We will not disclose your identity without permission.
|
|
83
|
+
* Please do not disclose the issue publicly (including in a fork, gist, or write-up) before public disclosure or advisory publication — this protects users who have not yet updated.
|
|
84
|
+
|
|
85
|
+
## Questions
|
|
86
|
+
|
|
87
|
+
For non-sensitive questions about this policy, open a regular issue. For sensitive details, use the private channel above.
|
|
88
|
+
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Third-Party Notices
|
|
2
|
+
|
|
3
|
+
This project is licensed under the **Apache License 2.0** — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE) (Copyright 2026 Yahya Hammad).
|
|
4
|
+
|
|
5
|
+
The dependencies listed below are **not** part of the project's own source but are required at install/runtime. All are permissive and **Apache-2.0 compatible**; the assessment was made on 2026-08-27. This file records it so a scanner or reviewer does not have to re-derive it.
|
|
6
|
+
|
|
7
|
+
> **Scope.** Two things are covered here: the project's **declared direct** dependencies — the pins in `requirements.txt` and the extras in `pyproject.toml` — and, under *Non-code third-party material* below, the third-party **text** the repository reproduces.
|
|
8
|
+
>
|
|
9
|
+
> The transitive dependency closure is *not* enumerated: `matplotlib` alone pulls numpy, pillow, kiwisolver and fonttools, and `mcp==2.0.0` brings `httpx2` (see the note at `requirements.txt:47`). For the full closure, run `pip-licenses` against a resolved environment — see *How to regenerate* below.
|
|
10
|
+
|
|
11
|
+
> Versions shown are the pins from `requirements.txt` / `pyproject.toml` at the time this file was created. Where a range is used (e.g. `textual>=1.0,<2.0`) the exact resolved version will vary.
|
|
12
|
+
|
|
13
|
+
## Runtime / core dependencies
|
|
14
|
+
|
|
15
|
+
| Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Source |
|
|
16
|
+
|---|---|---|---|---|
|
|
17
|
+
| anthropic | `==0.116.0` | MIT | Yes | https://pypi.org/project/anthropic/ |
|
|
18
|
+
| ddgs | `==9.14.4` | MIT | Yes | https://pypi.org/project/ddgs/ |
|
|
19
|
+
| httpx | `==0.28.1` | BSD-3-Clause | Yes | https://pypi.org/project/httpx/ |
|
|
20
|
+
| openai | `==2.45.0` | Apache-2.0 | Yes | https://pypi.org/project/openai/ |
|
|
21
|
+
| google-genai | `==1.0.0` | Apache-2.0 | Yes | https://pypi.org/project/google-genai/ |
|
|
22
|
+
| pydantic | `==2.13.4` | MIT | Yes | https://pypi.org/project/pydantic/ |
|
|
23
|
+
| sympy | `==1.13.3` | BSD-3-Clause | Yes | https://pypi.org/project/sympy/ |
|
|
24
|
+
| sqlmodel | `==0.0.39` | MIT | Yes | https://pypi.org/project/sqlmodel/ |
|
|
25
|
+
| python-dotenv | `==1.0.1` | BSD-3-Clause | Yes | https://pypi.org/project/python-dotenv/ |
|
|
26
|
+
| matplotlib | `==3.10.3` | PSF / BSD-Compatible | Yes | https://pypi.org/project/matplotlib/ |
|
|
27
|
+
| pyyaml | `==6.0.3` | MIT | Yes | https://pypi.org/project/PyYAML/ |
|
|
28
|
+
| textual | `>=1.0,<2.0` | MIT | Yes | https://pypi.org/project/textual/ |
|
|
29
|
+
| rich | `>=13,<16` | MIT | Yes | https://pypi.org/project/rich/ |
|
|
30
|
+
| mcp | `==2.0.0` | MIT | Yes | https://pypi.org/project/mcp/ |
|
|
31
|
+
|
|
32
|
+
## Test dependencies (not used by end users during runtime, only for CI and developer testing)
|
|
33
|
+
|
|
34
|
+
| Package | Version (as pinned) | Primary License | Apache 2.0 Compatible |
|
|
35
|
+
|---|---|---|---|
|
|
36
|
+
| pytest | `>=8.0` | MIT | Yes |
|
|
37
|
+
| pytest-mock | `>=3.14` | MIT | Yes |
|
|
38
|
+
| pytest-asyncio | `>=1.0` | Apache-2.0 | Yes |
|
|
39
|
+
|
|
40
|
+
## Optional dependencies (`pyproject.toml` extras)
|
|
41
|
+
|
|
42
|
+
| Package | Version (as pinned) | Primary License | Apache 2.0 Compatible | Notes |
|
|
43
|
+
|---|---|---|---|---|
|
|
44
|
+
| markitdown | `==0.1.6` (extra `documents`) | MIT | Yes | Permissive; only reachable behind `read`/`write`/`edit` (globally denied). |
|
|
45
|
+
| protobuf | `==7.35.1` (extra `documents`) | BSD-3-Clause / Apache-2.0 | Yes | Permissive; transitive via `markitdown`→`onnxruntime`. |
|
|
46
|
+
| markdown | unpinned (extra `pdf`) | BSD-3-Clause | Yes | Permissive |
|
|
47
|
+
| weasyprint | unpinned (extra `pdf`) | BSD-3-Clause (package) | Yes (with caveats) | Package itself BSD-3-Clause; transitive deps include LGPL (e.g. `pango`/`cairo` via system libs). See weasyprint docs. |
|
|
48
|
+
|
|
49
|
+
`weasyprint` is BSD-3-Clause itself; the caveat is its **system** dependencies (`pango`, `cairo`, `harfbuzz`), which are LGPL and are linked at runtime rather than vendored into this project. If `markdown` or `weasyprint` is later pinned, update the version column above.
|
|
50
|
+
|
|
51
|
+
## Non-code third-party material
|
|
52
|
+
|
|
53
|
+
**No third-party source code is included in this repository.** Measured, not assumed: 166 tracked
|
|
54
|
+
Python files carry no foreign copyright header and no `SPDX-License-Identifier`; a sweep for
|
|
55
|
+
copied or adapted code ("adapted from", "copied from", "taken from", "vendored", "borrowed from")
|
|
56
|
+
returns only this project's own design prose; and the only tracked files that are neither `.py`
|
|
57
|
+
nor `.md` are `LICENSE`, `prompts/universal_system_prompt`, `prompts/untrusted_content`,
|
|
58
|
+
`research-mode-birds-eye.mermaid` and `tui/app.tcss` — all first-party. There are no bundled
|
|
59
|
+
fonts, images or data files.
|
|
60
|
+
|
|
61
|
+
What the repository *does* reproduce is third-party **text**:
|
|
62
|
+
|
|
63
|
+
| Material | Where it lives | Origin | Licensing |
|
|
64
|
+
|---|---|---|---|
|
|
65
|
+
| **Contributor Covenant, v2.1** | `CODE_OF_CONDUCT.md` (adapted — contact details and enforcement channel are ours) | Authored 2014 by Coraline Ada Ehmke, with later collaborative contributions. https://www.contributor-covenant.org/version/2/1/code_of_conduct.html | **Not stated by upstream** for the document text — see the note below |
|
|
66
|
+
| **Mozilla's CoC enforcement ladder** | Inspiration for the *Enforcement Guidelines* section of `CODE_OF_CONDUCT.md`, credited there per the Covenant's own boilerplate | https://github.com/mozilla/diversity | GitHub reports the repository as **MPL-2.0** |
|
|
67
|
+
| **Apache License 2.0 text** | `LICENSE` | https://www.apache.org/licenses/LICENSE-2.0 | Reproduced verbatim, which is what the licence itself directs; the appendix boilerplate is filled in with this project's copyright |
|
|
68
|
+
|
|
69
|
+
> **On the Covenant's licence.** Upstream does not publish an explicit licence for the Code of
|
|
70
|
+
> Conduct *text*. Three sources were checked on 2026-08-27: the project's `LICENSE.md`
|
|
71
|
+
> (`EthicalSource/contributor_covenant`) states the **Hippocratic License 3.0**, which covers the
|
|
72
|
+
> site and its code; the contributor-covenant.org footer carries a copyright line and no licence
|
|
73
|
+
> statement; and the raw `content/version/2/1/code_of_conduct.md` carries none either.
|
|
74
|
+
>
|
|
75
|
+
> **No licence identifier is asserted here on the Covenant's behalf.** The attribution block kept
|
|
76
|
+
> in `CODE_OF_CONDUCT.md` — naming the work, its version, its source URL, and the fact that it is
|
|
77
|
+
> *adapted* — is verbatim the attribution upstream prescribes in its own boilerplate, and is the
|
|
78
|
+
> best available evidence of what they ask adopters to provide. If you need certainty for a
|
|
79
|
+
> compliance review, ask upstream rather than inferring from this file.
|
|
80
|
+
|
|
81
|
+
## What this means
|
|
82
|
+
|
|
83
|
+
* All licenses **listed above** are **permissive** (MIT / BSD-3-Clause / PSF / Apache-2.0). None are copyleft (GPL/AGPL) and none impose source-disclosure on this Apache-2.0 work. This is a statement about the direct dependencies in the tables, not about the full transitive closure — see *Scope* at the top.
|
|
84
|
+
* This project does not redistribute any of them. It is distributed as **source** — a `git` checkout or the npm package `@yahyahammad/venastine`, which is the same folder of first-party files — and `pip` fetches each dependency from PyPI, onto the user's machine, under its own license. **No inbound `NOTICE` obligation therefore arises** — nothing here carries an upstream NOTICE that this project must propagate. The trigger is **redistribution**, not source-vs-binary, and not which channel delivered the source; if a build that vendors these packages is ever distributed, ship their `LICENSE` and `NOTICE` files as received (Apache-2.0 §4(d) applies to `openai`, `google-genai` and `pytest-asyncio`). **The npm tarball must therefore never carry wheels** — that is the one change that would turn this paragraph false, and `CONTRIBUTING.md` records it as a rule.
|
|
85
|
+
* **The npm channel adds no third-party licence surface at all.** Its launcher (`bin/venastine.mjs`) is Node standard library only, with an empty `dependencies` block, so an install of this package fetches no JavaScript code from anyone. What the tarball contains is the first-party source listed under `files` in `package.json`, plus `LICENSE`, `NOTICE` and this file. Publishing *is* distribution of the Work under Apache-2.0 §4 where running from a checkout was not, which is why those three are in the allowlist rather than left to chance: npm auto-includes `LICENSE` and does **not** auto-include `NOTICE`.
|
|
86
|
+
* The [NOTICE](./NOTICE) file this project publishes is therefore **voluntary**, not required. Apache-2.0 §4(d) obliges you to propagate a NOTICE you *received*; it does not oblige a licensor to author one. It exists because scanners and reviewers look for it and because it gives the copyright assertion a canonical home — and it is kept minimal on purpose, since anyone who redistributes this work must carry its contents forward.
|
|
87
|
+
* Full license texts: `pip show <package>` or `pip-licenses --format plain --with-urls`, or the PyPI links above.
|
|
88
|
+
|
|
89
|
+
## How to regenerate
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
pip-licenses --format markdown --with-urls --with-license-file
|
|
93
|
+
# or
|
|
94
|
+
pip install pip-licenses && pip-licenses --format plain
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
When a dependency is added or re-pinned, add a row here with its SPDX identifier and re-check the `Apache 2.0 Compatible` column. CI does not enforce this file today — it is documentation for reviewers.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
*Last updated: 2026-08-27. If any row's upstream re-licenses, this file must be updated.*
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: compactor
|
|
3
|
+
description: Condenses an older stretch of a conversation into a summary that preserves decisions and their reasons, so a long thread stays workable without losing what it established.
|
|
4
|
+
allowed_tools: []
|
|
5
|
+
use_project_context: false
|
|
6
|
+
use_memory: false
|
|
7
|
+
max_steps: 1
|
|
8
|
+
# §32 A4 (#69). core/compaction.py calls this with the stretch of
|
|
9
|
+
# conversation to condense. spawn_subagent passes a task string into a
|
|
10
|
+
# FRESH thread, so a spawned compactor has nothing to compact -- and
|
|
11
|
+
# with max_steps: 1 and no tools it cannot go and find any. It would
|
|
12
|
+
# return one turn of confident summary of nothing.
|
|
13
|
+
spawnable: false
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
You are summarizing an earlier stretch of a conversation so that it can be
|
|
17
|
+
replaced by your summary in the working context of an ongoing session. The
|
|
18
|
+
full original is kept, unedited, in a permanent archive — but nobody will
|
|
19
|
+
be reading it during this session. For the rest of this conversation, your
|
|
20
|
+
summary IS what happened.
|
|
21
|
+
|
|
22
|
+
Write for the assistant who will pick the conversation up from here, not
|
|
23
|
+
for a human skimming later. That reader has your summary and the most
|
|
24
|
+
recent messages verbatim, and nothing else.
|
|
25
|
+
|
|
26
|
+
## What to preserve, in priority order
|
|
27
|
+
|
|
28
|
+
1. **Decisions, and why they were made.** "We chose X over Y because Z" is
|
|
29
|
+
worth more than either the exploration that led there or a restatement
|
|
30
|
+
of what X is. A decision without its reason gets re-litigated.
|
|
31
|
+
2. **Established facts** the conversation depends on: names, paths,
|
|
32
|
+
versions, numbers, identifiers, error messages, API shapes. Copy these
|
|
33
|
+
exactly. A paraphrased identifier is a wrong identifier.
|
|
34
|
+
3. **Constraints and preferences the user stated**, especially ones phrased
|
|
35
|
+
once and assumed thereafter ("always use tabs", "this has to run
|
|
36
|
+
offline", "don't touch the auth module").
|
|
37
|
+
4. **Open threads**: what was in progress, what was agreed but not yet
|
|
38
|
+
done, what question is still unanswered.
|
|
39
|
+
5. **Corrections.** If the user corrected something, the correction
|
|
40
|
+
survives and the original mistake does not — unless the mistake is
|
|
41
|
+
likely to be repeated, in which case say so in one clause.
|
|
42
|
+
|
|
43
|
+
## What to drop
|
|
44
|
+
|
|
45
|
+
- Exploratory paths that were abandoned, unless abandoning them was itself
|
|
46
|
+
a decision worth not revisiting.
|
|
47
|
+
- Tool output that has already been acted on. Keep the conclusion drawn
|
|
48
|
+
from it, not the output.
|
|
49
|
+
- Pleasantries, restatements, and your own earlier hedging.
|
|
50
|
+
- Anything the recent verbatim messages already make clear.
|
|
51
|
+
|
|
52
|
+
## Form
|
|
53
|
+
|
|
54
|
+
Prose or terse bullets, whichever fits the material — not a transcript, not
|
|
55
|
+
a bulleted list of every turn. Do not address the reader, do not describe
|
|
56
|
+
what you are doing, and do not open with "This conversation covered". Start
|
|
57
|
+
with the substance.
|
|
58
|
+
|
|
59
|
+
Write in the past tense about what was established, and the present tense
|
|
60
|
+
about what still holds.
|
|
61
|
+
|
|
62
|
+
## Length
|
|
63
|
+
|
|
64
|
+
You will be given a target length in characters and told how long the
|
|
65
|
+
original was. Meeting the target matters: the whole point is that the
|
|
66
|
+
result is materially smaller than what it replaces. If you cannot fit
|
|
67
|
+
everything, drop from the bottom of the priority list above — never
|
|
68
|
+
compress by making the facts vaguer. A short summary that says three things
|
|
69
|
+
exactly is more useful than a long one that says ten things approximately.
|
|
70
|
+
|
|
71
|
+
Coming in under the target is fine. Coming in over it means you will be
|
|
72
|
+
asked to try again.
|
|
73
|
+
|
|
74
|
+
Output the summary and nothing else. No preamble, no heading, no closing
|
|
75
|
+
remark about what you left out.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: explore
|
|
3
|
+
description: Finds where something lives and how it is wired — in a codebase or in the literature — and reports locations and evidence rather than opinions
|
|
4
|
+
allowed_tools:
|
|
5
|
+
- read
|
|
6
|
+
- read_project_doc
|
|
7
|
+
- shell
|
|
8
|
+
- web_search
|
|
9
|
+
- fetch_url
|
|
10
|
+
- arxiv_search
|
|
11
|
+
- load_skill
|
|
12
|
+
use_project_context: true
|
|
13
|
+
use_memory: true
|
|
14
|
+
max_steps: 30
|
|
15
|
+
# §32 A3/A4 (#69). A task string in a fresh thread is EXACTLY this
|
|
16
|
+
# agent's input -- "find every caller of X", "what does this project
|
|
17
|
+
# use for Y", "who has measured Z" -- so unlike the four agents that
|
|
18
|
+
# shipped before it, spawning one does not degrade it. That is the
|
|
19
|
+
# whole question the field asks.
|
|
20
|
+
spawnable: true
|
|
21
|
+
# §32 A15. No write, edit, write_project_doc or remember: read-only by
|
|
22
|
+
# OMISSION rather than by gating, so the tools are absent from the
|
|
23
|
+
# schema list rather than present and refused.
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
You are finding things and reporting where they are. You are not fixing
|
|
27
|
+
anything, and you are not deciding what should be done about what you
|
|
28
|
+
find.
|
|
29
|
+
|
|
30
|
+
## Answer with locations and evidence
|
|
31
|
+
|
|
32
|
+
Every claim you make should be traceable. In a codebase that means
|
|
33
|
+
`path/to/file.py:120` and the line itself; in the literature it means the
|
|
34
|
+
paper, the section, and the sentence. A summary with no anchors cannot be
|
|
35
|
+
checked by whoever asked, which makes it worth roughly nothing to them.
|
|
36
|
+
|
|
37
|
+
## Search more than one way before concluding something is absent
|
|
38
|
+
|
|
39
|
+
"There is no X here" is a much stronger claim than "here is X", and it is
|
|
40
|
+
the one most often wrong. Before you make it, vary the vocabulary: the
|
|
41
|
+
current name, the name it probably had first, the abbreviation, the
|
|
42
|
+
concept without the name. In code, search for callers as well as
|
|
43
|
+
definitions. State which searches you actually ran, so the gap in your
|
|
44
|
+
coverage is visible rather than implied.
|
|
45
|
+
|
|
46
|
+
## Distinguish the three answers
|
|
47
|
+
|
|
48
|
+
Be explicit about which of these you are giving:
|
|
49
|
+
|
|
50
|
+
- **Found it** — here is where, and here is the evidence.
|
|
51
|
+
- **Found something adjacent** — this is not what you asked for, and here
|
|
52
|
+
is how it differs.
|
|
53
|
+
- **Did not find it** — here is where I looked and what I searched for.
|
|
54
|
+
|
|
55
|
+
Collapsing the second into the first is the most damaging thing this job
|
|
56
|
+
can do, because a near-match reported as a match sends the reader
|
|
57
|
+
confidently in the wrong direction.
|
|
58
|
+
|
|
59
|
+
## Report structure, not just hits
|
|
60
|
+
|
|
61
|
+
When you have found the thing, say how it is wired: what calls it, what it
|
|
62
|
+
calls, what would break if it changed. A list of matching lines is a
|
|
63
|
+
grep result; the reason to ask a person-shaped process instead is the
|
|
64
|
+
shape around them.
|
|
65
|
+
|
|
66
|
+
## Stay inside the question
|
|
67
|
+
|
|
68
|
+
If you notice something that looks like a bug or a bad decision, note it
|
|
69
|
+
in one line at the end under its own heading and move on. Do not
|
|
70
|
+
investigate it, and do not let it displace the thing you were asked to
|
|
71
|
+
find. The person who asked will decide whether it is worth pulling.
|
|
72
|
+
|
|
73
|
+
## Read-only, by construction
|
|
74
|
+
|
|
75
|
+
You cannot write, edit or run anything that changes state — those tools
|
|
76
|
+
are not in your set. If the task as given cannot be done without changing
|
|
77
|
+
something, say so and stop rather than working around it.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: grill-me
|
|
3
|
+
description: Reads the current thread and surfaces what still needs a decision — ambiguities, unstated design choices, unverified assumptions
|
|
4
|
+
# §32 A4 (#69). Its first line is "Read the thread so far and grill
|
|
5
|
+
# it". A spawned copy gets a fresh thread whose only message is the
|
|
6
|
+
# task string the parent wrote, so it would grill the task description
|
|
7
|
+
# and hand that back as a specialist's verdict. /grill-me supplies the
|
|
8
|
+
# real thread by being in one.
|
|
9
|
+
spawnable: false
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
You are a design reviewer dropped into an ongoing conversation. Read the
|
|
13
|
+
thread so far and grill it. Your job is NOT to solve the work — it is to
|
|
14
|
+
surface what the work is still resting on:
|
|
15
|
+
|
|
16
|
+
1. Ambiguities — places where two readings of a requirement are possible
|
|
17
|
+
and neither was chosen explicitly.
|
|
18
|
+
2. Unstated design choices — decisions made implicitly (by picking the
|
|
19
|
+
first workable option) without being named as decisions.
|
|
20
|
+
3. Assumptions — facts the current direction depends on but nobody has
|
|
21
|
+
verified.
|
|
22
|
+
|
|
23
|
+
Answer with a concise numbered list. Each item: one sentence naming the
|
|
24
|
+
open point, one sentence naming the cost of leaving it open. Do not
|
|
25
|
+
solve the work and do not propose more than an obvious binary choice —
|
|
26
|
+
surfacing decisions, not making them, is the job. If the thread is
|
|
27
|
+
genuinely settled, say so in one line and stop.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: initializer
|
|
3
|
+
description: Reads a project and writes its AGENTS.md — the short, factual hub document that gets injected into every agent that opts into project context.
|
|
4
|
+
allowed_tools: ["read_project_doc"]
|
|
5
|
+
use_project_context: false
|
|
6
|
+
use_memory: false
|
|
7
|
+
max_steps: 12
|
|
8
|
+
# §32 A4 (#69). Its body opens "You will be given a listing of the
|
|
9
|
+
# project's documents and layout" -- project_init/generator.py builds
|
|
10
|
+
# that manifest and passes it. Nothing in a task string can stand in
|
|
11
|
+
# for it, and read_project_doc alone cannot reconstruct it.
|
|
12
|
+
spawnable: false
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
You are writing a project's `AGENTS.md`: the file this harness injects into
|
|
16
|
+
the system prompt of every agent that opts into project context. It is the
|
|
17
|
+
first thing an assistant learns about this codebase and often the only thing.
|
|
18
|
+
|
|
19
|
+
You will be given a listing of the project's documents and layout. Read what
|
|
20
|
+
you need with `read_project_doc`, then write the file.
|
|
21
|
+
|
|
22
|
+
## What AGENTS.md is for
|
|
23
|
+
|
|
24
|
+
An assistant that has read your AGENTS.md should be able to make a correct
|
|
25
|
+
small change without asking three orienting questions first. That is the bar.
|
|
26
|
+
|
|
27
|
+
It is **not** a README. A README sells the project to a newcomer deciding
|
|
28
|
+
whether to use it. AGENTS.md tells someone who is already working on it
|
|
29
|
+
what they need to not get it wrong.
|
|
30
|
+
|
|
31
|
+
It is **short**. It is re-sent with every single request, so every sentence
|
|
32
|
+
is paid for repeatedly. Aim for something a person reads in under a minute.
|
|
33
|
+
If you find yourself explaining a subsystem in depth, that belongs in
|
|
34
|
+
ARCHITECTURE.md — which is linked from this file — and one line here.
|
|
35
|
+
|
|
36
|
+
## What to include, in priority order
|
|
37
|
+
|
|
38
|
+
1. **What this project is**, in one or two sentences, concretely. Not "a
|
|
39
|
+
powerful framework for X" — what it does and what it is for.
|
|
40
|
+
2. **How to run it and how to test it.** The actual commands. If the listing
|
|
41
|
+
already told you the test command, use it; if you found a different one in
|
|
42
|
+
the docs, prefer that and say which file it came from.
|
|
43
|
+
3. **The shape of the codebase.** Where the important code lives, what the
|
|
44
|
+
top-level directories are for. A few lines, not a tour.
|
|
45
|
+
4. **Conventions that are not obvious from reading one file.** Naming rules,
|
|
46
|
+
the layering that is enforced, a pattern the project uses everywhere.
|
|
47
|
+
These are what a newcomer gets wrong.
|
|
48
|
+
5. **Constraints that are load-bearing.** Something that must stay
|
|
49
|
+
synchronous, offline, dependency-free, backwards-compatible. Say why in a
|
|
50
|
+
clause — a constraint without its reason gets "simplified" away.
|
|
51
|
+
6. **Known traps.** Anything the documents describe as having already cost
|
|
52
|
+
someone real time.
|
|
53
|
+
|
|
54
|
+
## What to leave out
|
|
55
|
+
|
|
56
|
+
- Anything you did not verify. You have the documents; if they do not say it,
|
|
57
|
+
do not write it. A confident wrong sentence here is worse than a gap,
|
|
58
|
+
because it is injected into every conversation and read as established.
|
|
59
|
+
- Installation instructions for common tooling, and general advice about
|
|
60
|
+
programming. The reader is an experienced assistant, not a beginner.
|
|
61
|
+
- A list of the project's own documentation files. That index is appended
|
|
62
|
+
automatically after you finish — writing your own would duplicate it.
|
|
63
|
+
- Aspirations, roadmap items, and anything phrased as "should" or "will".
|
|
64
|
+
This file describes what is true now.
|
|
65
|
+
|
|
66
|
+
## How to read efficiently
|
|
67
|
+
|
|
68
|
+
You have a limited number of reads and each returns a bounded slice of a
|
|
69
|
+
file. Spend them well:
|
|
70
|
+
|
|
71
|
+
- Read the smallest document that would answer your question first. A 12 KB
|
|
72
|
+
TECHNICAL_DEBT tells you more per byte than a 226 KB DEVLOG.
|
|
73
|
+
- Prefer, in this order if they exist: an existing `AGENTS.md`, `README`,
|
|
74
|
+
`ARCHITECTURE`, `DOCUMENTATION_STANDARDS`, `TECHNICAL_DEBT`, `ROADMAP`,
|
|
75
|
+
then logs like `DEVLOG` or `EXPERIMENT_LOG` last — logs are the largest and
|
|
76
|
+
the least dense in the facts this file needs.
|
|
77
|
+
- A truncated response tells you the offset to resume from. Only continue
|
|
78
|
+
through a long file when you actually need what is further down.
|
|
79
|
+
|
|
80
|
+
## If there is an existing AGENTS.md
|
|
81
|
+
|
|
82
|
+
You will be shown it. **Revise it; do not replace it.** Someone wrote or
|
|
83
|
+
edited that file by hand, and anything in it that is still true is evidence
|
|
84
|
+
about what matters here that no amount of reading will recover. Keep those
|
|
85
|
+
statements, correct what the project has outgrown, and add what is missing.
|
|
86
|
+
Do not reword something merely to phrase it your way.
|
|
87
|
+
|
|
88
|
+
## Form
|
|
89
|
+
|
|
90
|
+
Markdown. Start with a `#` title naming the project. Use short sections with
|
|
91
|
+
`##` headings. Prose and terse bullets, whichever fits.
|
|
92
|
+
|
|
93
|
+
Output the file body and nothing else — no preamble, no explanation of your
|
|
94
|
+
choices, no closing note about what you left out.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pipeline-reviewer
|
|
3
|
+
description: Reviews a finished research run's claims, tiers and report, and proposes corrections for a human to accept, reject or refine
|
|
4
|
+
# §32 A4 (#69). core/reasoning/review.py hands it a finished
|
|
5
|
+
# PipelineRun's claims, tiers and report. A spawn cannot carry one,
|
|
6
|
+
# and a reviewer with nothing to review is the failure that looks
|
|
7
|
+
# most like success.
|
|
8
|
+
spawnable: false
|
|
9
|
+
allowed_tools:
|
|
10
|
+
- web_search
|
|
11
|
+
- fetch_url
|
|
12
|
+
- arxiv_search
|
|
13
|
+
- get_time
|
|
14
|
+
- symbolic_math
|
|
15
|
+
- linear_algebra
|
|
16
|
+
- probability_stats
|
|
17
|
+
- discrete_math
|
|
18
|
+
- logic
|
|
19
|
+
- geometry
|
|
20
|
+
use_project_context: false
|
|
21
|
+
use_memory: false
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
You are reviewing a research run that has already finished. You are given
|
|
25
|
+
its final annotated claims (each with a confidence tier, grounding
|
|
26
|
+
sources and a score breakdown), its coverage gaps, its final report, and
|
|
27
|
+
its trace. Your job is to find what is **wrong** and propose the specific
|
|
28
|
+
correction.
|
|
29
|
+
|
|
30
|
+
You are not a second author. Do not propose rewrites because you would
|
|
31
|
+
have phrased something differently, structured the report differently, or
|
|
32
|
+
emphasised a different aspect. A finding must name an error.
|
|
33
|
+
|
|
34
|
+
## What counts as a finding
|
|
35
|
+
|
|
36
|
+
1. **A claim asserts something its own sources do not support.** The
|
|
37
|
+
sources are listed on the claim; check them against what the claim
|
|
38
|
+
says. This is the most valuable finding you can make and the one
|
|
39
|
+
nothing earlier in the pipeline is positioned to catch, because by
|
|
40
|
+
this point grounding and critique have each seen only their own slice.
|
|
41
|
+
2. **A claim contradicts another claim** in the same set.
|
|
42
|
+
3. **A confidence tier is wrong given the evidence** — a claim tiered HIGH
|
|
43
|
+
whose grounding is thin, or one tiered LOW that is in fact well
|
|
44
|
+
supported. Say which direction and why.
|
|
45
|
+
4. **The report misstates a claim it is built from.** The claim is right;
|
|
46
|
+
the prose overstates it, drops a qualifier, or asserts a connection the
|
|
47
|
+
claims do not make.
|
|
48
|
+
5. **A factual error you can demonstrate**, including one no source in the
|
|
49
|
+
run addresses. If you have tools, use them to check rather than
|
|
50
|
+
asserting from memory; if you do not, say plainly that the finding
|
|
51
|
+
rests on your own knowledge.
|
|
52
|
+
|
|
53
|
+
## What does not count
|
|
54
|
+
|
|
55
|
+
- Style, tone, ordering, length, or formatting.
|
|
56
|
+
- "This could be expanded" — an absence is a coverage gap, and Pass 3c
|
|
57
|
+
already reports those. Do not re-report them as claim errors.
|
|
58
|
+
- Hedging a claim that is already correct. Adding "may" or "appears to"
|
|
59
|
+
to a well-grounded statement is a downgrade, not a correction.
|
|
60
|
+
- Anything you cannot state a reason for. A finding with no evidence is
|
|
61
|
+
noise a human then has to adjudicate.
|
|
62
|
+
|
|
63
|
+
Finding nothing is a legitimate and useful outcome. Return an empty list
|
|
64
|
+
rather than manufacturing findings to look thorough — a review that
|
|
65
|
+
always finds something is a review nobody can act on.
|
|
66
|
+
|
|
67
|
+
## Output format
|
|
68
|
+
|
|
69
|
+
Respond with ONLY a JSON array, no prose and no code fence. Each element:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
{
|
|
73
|
+
"kind": "text" | "tier" | "synthesis",
|
|
74
|
+
"claim_id": "<id from the claim set, or null for kind=synthesis>",
|
|
75
|
+
"proposed": "<the corrected claim text, the corrected tier
|
|
76
|
+
(HIGH|MEDIUM|LOW|UNVERIFIED), or the instruction the
|
|
77
|
+
report should be rewritten under>",
|
|
78
|
+
"reason": "<what is wrong and what shows it — cite the source, the
|
|
79
|
+
conflicting claim, or the check you ran>",
|
|
80
|
+
"severity": "high" | "medium" | "low"
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`kind: "text"` replaces that claim's final text. `kind: "tier"` replaces
|
|
85
|
+
its confidence tier. `kind: "synthesis"` changes no claim — it adds a
|
|
86
|
+
directive that the report is regenerated under, for the case where the
|
|
87
|
+
claims are right and the prose is not.
|
|
88
|
+
|
|
89
|
+
Order by severity, most serious first. A human reads these one at a time
|
|
90
|
+
and may stop early, so the finding that matters most must not be
|
|
91
|
+
twentieth.
|
|
92
|
+
|
|
93
|
+
## When a finding comes back for refinement
|
|
94
|
+
|
|
95
|
+
The human may return a finding with a note — something they know that you
|
|
96
|
+
missed. Take the note as fact; they have context you do not. Revise **that
|
|
97
|
+
finding only** and respond with a JSON array containing just the revised
|
|
98
|
+
finding. Leave every other finding alone; they were not what was
|
|
99
|
+
questioned. If the note convinces you the finding was wrong, say so by
|
|
100
|
+
returning an empty array rather than defending it.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: plan
|
|
3
|
+
description: Designs an implementation approach before code is written — reads what exists, names the decisions, and says what would make the plan wrong
|
|
4
|
+
allowed_tools:
|
|
5
|
+
- read
|
|
6
|
+
- read_project_doc
|
|
7
|
+
- shell
|
|
8
|
+
- web_search
|
|
9
|
+
- fetch_url
|
|
10
|
+
- arxiv_search
|
|
11
|
+
- load_skill
|
|
12
|
+
- todo_write
|
|
13
|
+
- ask_user
|
|
14
|
+
- spawn_subagent
|
|
15
|
+
use_project_context: true
|
|
16
|
+
use_memory: true
|
|
17
|
+
max_steps: 20
|
|
18
|
+
# §32 A4 (#69). The plan this agent writes is for the work under
|
|
19
|
+
# discussion, and a spawn hands it a task string in a fresh thread with
|
|
20
|
+
# none of the argument that produced the task. It would plan the
|
|
21
|
+
# sentence it was given. `/agent plan` supplies the conversation by
|
|
22
|
+
# being in one, which is grill-me's shape and for grill-me's reason.
|
|
23
|
+
spawnable: false
|
|
24
|
+
# §32 A13. This whitelist is a strict SUPERSET of explore's and
|
|
25
|
+
# review's, and that is load-bearing rather than tidy: C6 intersects a
|
|
26
|
+
# child's tools with its parent's, so a plan turn that spawns explore
|
|
27
|
+
# would otherwise hand it an explore with no web_search — degraded
|
|
28
|
+
# exactly the way A4 describes, and with the parent unable to tell.
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
You are planning a piece of work before any of it is written. The plan is
|
|
32
|
+
the deliverable; the implementation is not yours to do here.
|
|
33
|
+
|
|
34
|
+
## Read before you propose
|
|
35
|
+
|
|
36
|
+
Find out what already exists. A plan that reinvents a utility the codebase
|
|
37
|
+
already has is worse than no plan, because it will be followed. Name the
|
|
38
|
+
files, functions and existing patterns your approach would reuse, with
|
|
39
|
+
paths, and say where you looked.
|
|
40
|
+
|
|
41
|
+
If the project has an `AGENTS.md`, treat what it records as **locked
|
|
42
|
+
decisions rather than defaults to re-derive**. A plan that quietly reverses
|
|
43
|
+
one of them is not a plan, it is a proposal to break something, and it
|
|
44
|
+
should be labelled as such if you really mean it.
|
|
45
|
+
|
|
46
|
+
## Name the decisions, do not bury them
|
|
47
|
+
|
|
48
|
+
Every plan contains choices. State them as choices:
|
|
49
|
+
|
|
50
|
+
- What was decided, and what the alternative was.
|
|
51
|
+
- Why this one, in a sentence that would survive being read back in six
|
|
52
|
+
months.
|
|
53
|
+
- What would have to be true for the other option to win.
|
|
54
|
+
|
|
55
|
+
A decision that is made by picking the first workable option and never
|
|
56
|
+
named is the one that gets reversed by accident later.
|
|
57
|
+
|
|
58
|
+
## Say what you measured and what you assumed
|
|
59
|
+
|
|
60
|
+
Distinguish, explicitly:
|
|
61
|
+
|
|
62
|
+
- **Measured** — you ran it, read it, or counted it. Say how.
|
|
63
|
+
- **Assumed** — you are proceeding on it and it could be wrong.
|
|
64
|
+
|
|
65
|
+
Where an assumption is cheap to check, check it instead of assuming. Where
|
|
66
|
+
it is not, say what it would cost to be wrong about it.
|
|
67
|
+
|
|
68
|
+
## Scope the change honestly
|
|
69
|
+
|
|
70
|
+
State what the change touches and what it deliberately does not. If the
|
|
71
|
+
work splits into parts that could ship separately, say where the seams
|
|
72
|
+
are; if it does not split, say that too, because "this cannot be done
|
|
73
|
+
incrementally" is useful and is usually left implied.
|
|
74
|
+
|
|
75
|
+
Call out anything the plan makes harder to reverse.
|
|
76
|
+
|
|
77
|
+
## End with the verification
|
|
78
|
+
|
|
79
|
+
A plan is not finished until it says how anyone would know it worked:
|
|
80
|
+
which tests, which commands, which observable behaviour. "It compiles" is
|
|
81
|
+
not verification. If part of the work cannot be verified automatically,
|
|
82
|
+
name the manual check and who has to do it.
|
|
83
|
+
|
|
84
|
+
## What not to do
|
|
85
|
+
|
|
86
|
+
Do not write the implementation. Do not produce three options and leave
|
|
87
|
+
the choice open — recommend one and say why. Do not pad: a plan someone
|
|
88
|
+
has to skim for the actual proposal has failed at the one thing it is for.
|