@svayam-opensource/prj 0.5.3 → 0.5.4

package/README.md

@@ -9,7 +9,7 @@ of GitHub, under your organization's policy. You run `prj` and follow the menus;
 
 ## The framework has two components
 
-![The framework has two components — Governance Content (the rules and scaffolding) and Governance Actions (prj, the client that acts) — both operating on your governance workspace; adopt Content first, then act with prj.](https://cdn.jsdelivr.net/npm/@svayam-opensource/prj@0.5.3/assets/readme/two-components.svg)
+![The framework has two components — Governance Content (the rules and scaffolding) and Governance Actions (prj, the client that acts) — both operating on your governance workspace; adopt Content first, then act with prj.](https://cdn.jsdelivr.net/npm/@svayam-opensource/prj@latest/assets/readme/two-components.svg)
 
 1. **Governance Content** — the policies, knowledge structure, agent harness, and
    scaffolding that define *how* your org governs agentic work. **This lives in the
@@ -37,15 +37,29 @@ Runtime prerequisites (not npm dependencies — `prj` is bash): `bash`, `git`,
 `gh` (authenticated), `yq`, `python3`. On Windows, run inside **Git Bash**.
 
 ### Sequencing — Content first, then Actions
-![Sequencing — adopt Governance Content from the template repo and run setup, then configure your workspace via org-config.yaml, then run prj to take Actions.](https://cdn.jsdelivr.net/npm/@svayam-opensource/prj@0.5.3/assets/readme/sequencing.svg)
-`prj` acts *on* a configured governance workspace. **Set up Governance Content
-first** (from the template repo), **then** use `prj`. Run `prj` from anywhere
-inside the workspace (it finds it via `$ADF_WORKSPACE` or the nearest
-`org-config.yaml`).
+![Sequencing — adopt Governance Content from the template repo and run setup, then configure your workspace via org-config.yaml, then run prj to take Actions.](https://cdn.jsdelivr.net/npm/@svayam-opensource/prj@latest/assets/readme/sequencing.svg)
+`prj` acts *on* a configured governance workspace. **Which path applies to you
+depends on whether your org has already adopted the framework:**
+
+- **First-time adopter — you're the governance owner/admin for your org.**
+  Set up **Governance Content first** from the
+  [template repo](https://github.com/svayam-opensource/governed-agentic-dev-framework)
+  (clone it, run its `setup.sh`, fill in `org-config.yaml`), **then** install and
+  run `prj`. You are the one who copies and tailors the content.
+- **Your org already runs the framework — you're a developer/contributor.**
+  **Do not copy the template or re-run setup.** Your governance admin has already
+  adopted and customized the content. Just `npm i -g @svayam-opensource/prj`, get
+  the **workspace location from your governance admin**, and run `prj` from inside
+  it (or point `$ADF_WORKSPACE` at it). For anything about the governance content
+  itself — policies, knowledge, the agent harness, who owns what — **contact your
+  org's governance admin**, not this README.
+
+Run `prj` from anywhere inside the workspace (it finds it via `$ADF_WORKSPACE` or
+the nearest `org-config.yaml`).
 
 ### Dependencies — GitHub is the substrate
 `prj` keeps no separate database. Every fact lives in GitHub:
-![Dependencies — prj keeps no database; every fact lives in GitHub: Projects (a board IS a project, ownership and status), Issues (units of work, the anchor issue carries ownership), Repos (where code lives, derived from the board's issues), and GitHub Actions (CI gates that enforce the policy).](https://cdn.jsdelivr.net/npm/@svayam-opensource/prj@0.5.3/assets/readme/dependencies.svg)
+![Dependencies — prj keeps no database; every fact lives in GitHub: Projects (a board IS a project, ownership and status), Issues (units of work, the anchor issue carries ownership), Repos (where code lives, derived from the board's issues), and GitHub Actions (CI gates that enforce the policy).](https://cdn.jsdelivr.net/npm/@svayam-opensource/prj@latest/assets/readme/dependencies.svg)
 
 ### Journeys — *how do I…?*
 You don't need the command list. Run **`prj`** and follow the menu (every step is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svayam-opensource/prj",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Governed Agentic Development Framework CLI (prj). A bash CLI wrapped for npm; operates on a governance workspace resolved via $ADF_WORKSPACE or the nearest org-config.yaml. Runtime prerequisites (not npm deps): bash, git, gh, yq, python3 (use Git Bash on Windows).",
   "bin": {
     "prj": "bin/prj"
@@ -9,7 +9,6 @@
     "prj",
     "bin/",
     "setup.sh",
-    "agent/",
     "scripts/*.sh",
     "scripts/validate/*.py",
     "assets/readme/*.svg"

package/scripts/bump-version.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+#
+# bump-version.sh <x.y.z[-pre]>
+#
+# Single action that writes the release version into the three internal places
+# that must agree:
+#
+#   1. package.json        -> "version"
+#   2. framework/VERSION
+#   3. .framework-version
+#
+# The README diagram images are served by jsDelivr from the published npm
+# tarball via the floating `@latest` tag, so they are NOT version-pinned and
+# need no edit here. scripts/validate/check_version_sync.py enforces all of
+# this in CI and in the Jenkins publish gate.
+#
+# Usage:
+#   scripts/bump-version.sh 0.5.4
+#   then: review `git diff`, commit, push, trigger the publish webhook.
+#
+set -euo pipefail
+
+new="${1:-}"
+if [ -z "$new" ]; then
+  echo "usage: scripts/bump-version.sh <x.y.z>" >&2
+  exit 2
+fi
+case "$new" in
+  [0-9]*.[0-9]*.[0-9]*) : ;;
+  *) echo "error: '$new' is not a version (expected x.y.z)" >&2; exit 2 ;;
+esac
+
+root="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$root"
+
+# package.json: targeted replace of the top-level "version" value only — keeps
+# the file's existing formatting intact (no full re-serialize).
+NEW="$new" perl -0pi -e 's/("version"\s*:\s*")[^"]*(")/$1.$ENV{NEW}.$2/e' package.json
+printf '%s\n' "$new" > framework/VERSION
+printf '%s\n' "$new" > .framework-version
+
+echo "bumped -> $new"
+echo "  package.json       $(grep -m1 '"version"' package.json | tr -d ' ,')"
+echo "  framework/VERSION  $(cat framework/VERSION)"
+echo "  .framework-version $(cat .framework-version)"
+echo
+echo "next: review 'git diff', commit + push, then trigger the publish webhook."

package/scripts/validate/check_version_sync.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""
+Version-sync validator.
+
+The package version lives in three places that MUST agree, or installs and the
+downgrade guard misbehave:
+
+    1. package.json            -> "version"   (the source of truth)
+    2. framework/VERSION       (shipped framework version)
+    3. .framework-version      (install marker read by setup.sh on upgrade)
+
+The README's diagram images are served by jsDelivr out of the published npm
+tarball, referenced with the FLOATING `@latest` tag — so they are deliberately
+NOT version-pinned and need no bump. This check also guards that nobody
+accidentally re-pins them to an exact version (which would silently go stale on
+the next release).
+
+Bump all three with: scripts/bump-version.sh <x.y.z>
+
+Run standalone (the Jenkins publish gate does this):
+    python3 scripts/validate/check_version_sync.py [REPO_ROOT]
+Exits 0 on pass, 1 on drift.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+# jsDelivr URLs for THIS package in the README. Capture the version spec.
+_README_PIN_RE = re.compile(
+    r"cdn\.jsdelivr\.net/npm/@svayam-opensource/prj@([^/]+)/"
+)
+
+
+def check_version_sync(repo_root: Path) -> list[str]:
+    errors: list[str] = []
+
+    pkg_path = repo_root / "package.json"
+    if not pkg_path.exists():
+        return ["package.json not found"]
+    try:
+        version = (json.loads(pkg_path.read_text()).get("version") or "").strip()
+    except json.JSONDecodeError as e:
+        return [f"package.json does not parse: {e}"]
+    if not version:
+        return ["package.json: no 'version' field"]
+
+    # The two plain-text version files must equal package.json exactly.
+    for rel in ("framework/VERSION", ".framework-version"):
+        p = repo_root / rel
+        if not p.exists():
+            errors.append(f"{rel}: missing (expected to equal package.json {version})")
+            continue
+        got = p.read_text().strip()
+        if got != version:
+            errors.append(f"{rel}: {got!r} != package.json {version!r}")
+
+    # README diagram URLs must stay on @latest (floating), never an exact pin.
+    readme = repo_root / "README.md"
+    if readme.exists():
+        for spec in _README_PIN_RE.findall(readme.read_text()):
+            if spec != "latest":
+                errors.append(
+                    f"README.md: jsDelivr URL is pinned to @{spec}; use @latest "
+                    f"(diagram assets ship in the package and float with the release)"
+                )
+
+    return errors
+
+
+def main() -> int:
+    repo_root = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    errors = check_version_sync(repo_root)
+    if errors:
+        print(f"[FAIL] version-sync ({len(errors)} error{'s' if len(errors) != 1 else ''}):")
+        for e in errors:
+            print(f"   - {e}")
+        return 1
+    print("[PASS] version-sync")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate/run.py

@@ -27,6 +27,7 @@ sys.path.insert(0, str(Path(__file__).parent))
 from check_knowledge import check_knowledge  # noqa: E402
 from check_secrets import check_secrets  # noqa: E402
 from check_protocol import check_protocol  # noqa: E402
+from check_version_sync import check_version_sync  # noqa: E402
 
 try:
     import yaml
@@ -355,6 +356,7 @@ CHECKS = [
     ("knowledge-org", check_knowledge),
     ("secrets",     check_secrets),
     ("protocol",    check_protocol),
+    ("version-sync", check_version_sync),
 ]
 
 

package/agent/harness-manifest.yaml

@@ -1,225 +0,0 @@
-# Harness manifest — drives scripts/render-harness.sh
-# Canonical protocol: agent/session-protocol.md + agent.md
-# Spec: docs/design/agent-context-assembly-spec.md §3.3, Appendix C, Appendix D
-#
-# Do not hand-edit generated install paths listed under harnesses[].path when
-# generated: true. Run ./scripts/render-harness.sh after editing session-protocol.
-
-version: 1
-
-canonical:
-  session_protocol: agent/session-protocol.md
-  org_entrypoint: framework/agent.md
-  adopter_marker: "<!-- ADOPTER_C03_EXTENSIONS -->"
-
-# Delivery tiers (see spec Appendix D)
-#   import         — file expand at launch (@import); Claude Code only today
-#   generate_auto  — render-harness embeds protocol; tool auto-loads install path
-#   generate_manual— render-harness embeds protocol; developer must invoke (--read)
-#   fallback       — no repo convention; paste ./prj context assemble output
-
-tiers:
-  import:
-    description: Expand canonical files into startup context at tool launch
-  generate_auto:
-    description: Generated install path auto-loaded by the tool
-  generate_manual:
-    description: Generated file exists but developer must pass a flag or slash-command
-  fallback:
-    description: No install path; use kickoff prompt + transcript reads
-
-generated_banner: "<!-- GENERATED FROM agent/session-protocol.md — do not edit; run ./scripts/render-harness.sh -->"
-
-harnesses:
-  # ── Tier: import ──────────────────────────────────────────────────────────
-  - id: claude-code
-    tool: Claude Code
-    status: active
-    tier: import
-    path: framework/CLAUDE.md
-    generated: false
-    seed_copy: true
-    per_project_path: projects/{project_id}/CLAUDE.md
-    per_project_template: |
-      @../../agent/session-protocol.md
-      @agent.md
-
-      <!-- ADOPTER_C03_EXTENSIONS -->
-    verify: "Run /memory — must list CLAUDE.md and imported agent files"
-    notes: |
-      Claude does not read AGENTS.md unless @AGENTS.md is added.
-      First @import shows approval dialog once per project.
-
-  # ── Tier: generate_auto ───────────────────────────────────────────────────
-  - id: cursor
-    tool: Cursor
-    status: active
-    tier: generate_auto
-    path: framework/.cursor/rules/agent.mdc
-    generated: true
-    seed_copy: true
-    template: cursor-mdc
-    template_extra:
-      description: "Agentic Development Framework — session-start protocol (POL-113..117)"
-      globs: '["**/*"]'
-      alwaysApply: true
-    verify: "Cursor Settings → Rules — agent.mdc must show Always"
-    notes: |
-      Injected on every Chat/Agent/Composer turn when alwaysApply is true.
-      Inline Edit (Cmd+K) may not receive full rules.
-
-  - id: openai-codex
-    tool: OpenAI Codex
-    status: active
-    tier: generate_auto
-    path: framework/AGENTS.md
-    generated: true
-    seed_copy: true
-    template: markdown-plain
-    verify: "First message — ask agent to summarize session protocol"
-    notes: "Plain markdown; Codex CLI, Codex Web, ChatGPT coding mode."
-
-  - id: gemini-code-assist
-    tool: Gemini Code Assist
-    status: active
-    tier: generate_auto
-    path: framework/.gemini/styleguide.md
-    generated: true
-    seed_copy: true
-    template: markdown-plain
-    verify: "First message — ask what styleguide/rules were loaded"
-    notes: |
-      Convention name is styleguide; content is session protocol.
-      Re-check Google docs when extension updates.
-
-  - id: github-copilot
-    tool: GitHub Copilot
-    status: active
-    tier: generate_auto
-    path: framework/.github/copilot-instructions.md
-    generated: true
-    seed_copy: true
-    template: markdown-plain
-    verify: "Copilot assist on a repo file — ask it to state write restrictions"
-    notes: |
-      Edit-time assist, not a full agent session. Weaker C01 gate than Cursor/Claude.
-      Same folder holds GitHub Actions — do not mix CI config into instructions.
-
-  - id: windsurf
-    tool: Windsurf
-    status: active
-    tier: generate_auto
-    path: framework/.windsurf/rules/agent.md
-    generated: true
-    seed_copy: true
-    template: markdown-plain
-    verify: "First message — confirm rules loaded"
-
-  - id: cline
-    tool: Cline / Roo Code
-    status: active
-    tier: generate_auto
-    path: framework/.clinerules/agent.md
-    generated: true
-    seed_copy: true
-    template: markdown-plain
-    verify: "Open projects/{project_id}/ as workspace; confirm rules on startup"
-    notes: "Supports nested .clinerules/ per subdirectory."
-
-  - id: continue
-    tool: Continue.dev
-    status: active
-    tier: generate_auto
-    path: framework/.continue/rules.md
-    generated: true
-    seed_copy: true
-    template: markdown-plain
-    verify: "First message — confirm system rules loaded"
-    notes: "Complements .continue/config.yaml context providers."
-
-  # ── Tier: generate_manual ─────────────────────────────────────────────────
-  - id: aider
-    tool: Aider
-    status: active
-    tier: generate_manual
-    path: framework/CONVENTIONS.md
-    generated: true
-    seed_copy: true
-    template: markdown-plain
-    invoke: "aider --read CONVENTIONS.md …"
-    verify: "Confirm CONVENTIONS.md in aider context at session start"
-
-  # ── Tier: fallback (registered, not generated) ────────────────────────────
-  - id: chatgpt-web
-    tool: ChatGPT (web) / custom GPT
-    status: registered
-    tier: fallback
-    path: null
-    verify: "Paste kickoff prompt from DEVELOPER_GUIDE §3"
-    notes: "No repo-local auto-load."
-
-  - id: jetbrains-ai
-    tool: JetBrains AI Assistant
-    status: planned
-    tier: generate_auto
-    path: .junie/guidelines.md
-    generated: true
-    seed_copy: false
-    template: markdown-plain
-    notes: "Verify path against JetBrains docs before enabling."
-
-  - id: amazon-q
-    tool: Amazon Q Developer
-    status: planned
-    tier: generate_auto
-    path: .amazonq/rules.md
-    generated: true
-    seed_copy: false
-    template: markdown-plain
-    notes: "Path TBD — confirm with AWS docs before enabling."
-
-  - id: sourcegraph-cody
-    tool: Sourcegraph Cody
-    status: planned
-    tier: generate_auto
-    path: .sourcegraph/cody-rules.md
-    generated: true
-    seed_copy: false
-    template: markdown-plain
-    notes: "Path TBD."
-
-# Templates (consumed by render-harness.sh)
-templates:
-  cursor-mdc: |
-    ---
-    description: {{template_extra.description}}
-    globs: {{template_extra.globs}}
-    alwaysApply: {{template_extra.alwaysApply}}
-    ---
-
-    {{render.generated_banner}}
-
-    {{render.body}}
-  markdown-plain: |
-    {{render.generated_banner}}
-
-    {{render.body}}
-  claude-import-stub: |
-    @agent/session-protocol.md
-    @agent.md
-
-    <!-- ADOPTER_C03_EXTENSIONS -->
-
-# Per-project composition (seed / render-harness --project)
-per_project:
-  compose_body: |
-    {{render.session_protocol_body}}
-
-    ---
-
-    # Project entrypoint
-
-    @agent.md
-  note: |
-    For Cursor/Aider/etc., render-harness concatenates session-protocol + projects/PID/agent.md
-    into the generated install path. For Claude, per_project_template uses separate @imports.

package/agent/session-protocol.md

@@ -1,116 +0,0 @@
-# Agent Session-Start Protocol — <ORG_NAME>
-
-This is the **canonical** session-start protocol for any AI coding agent working in this workspace. It is delivered to each tool at its conventional path (`CLAUDE.md`, `.cursor/rules/agent.mdc`, `AGENTS.md`, `CONVENTIONS.md`, …) by `scripts/render-harness.sh`, driven by `agent/harness-manifest.yaml`. **Edit the protocol here, then re-render — never hand-edit the generated copies** (they carry a "do not edit" banner).
-
-## 0. New session — agent speaks first (Pattern 1)
-
-**Applies to:** every new Cursor Agent/Chat session, every new `claude` invocation, and every new conversation after `/clear`.
-
-When this protocol is loaded, your **first assistant message** in the session must run the C01 checklist (§1–§2 below) and post a **context manifest** — **before** planning work, proposing tasks, or editing files.
-
-| Trigger | What you do |
-|---|---|
-| User's first message is a greeting, "start", "go", "ready", or session opener | Run §1–§2, post manifest, **stop and wait** |
-| User's first message already contains a **specific work task** | Still run §1–§2 first; post a **short** manifest, then address the task |
-| No active project (framework/contrib mode; no `active` entry in `registry.yaml`) | Post manifest stating no active project; load org layer + `agent.md` only; wait for direction |
-
-**Do not** wait for the user to paste the kickoff prompt from `DEVELOPER_GUIDE.md` — that template is for humans; you execute the same steps proactively.
-
-### Context manifest (required format)
-
-Use this structure in your first reply:
-
-```markdown
-## Context manifest
-
-- **Project:** <PROJECT_ID or "none">
-- **Branch:** <current git branch>
-- **Status / assigned_to:** <from project.yaml, or n/a>
-- **Repos:** <primary repos from project.yaml, or n/a>
-- **Open todos:** <bullets from todo.md ## Open, or "none">
-- **Layers loaded:** org ✓/✗ · project ✓/✗ · repo ✓/✗ · prefs ✓/✗
-- **Awaiting:** your direction (no tasks proposed)
-```
-
-After the manifest, **stop**. Do not propose implementation work unless the user's first message already asked for something specific — and even then, complete the manifest first.
-
----
-
-Before you change any code, complete the steps below.
-
-## 1. Read `org-config.yaml` first — every framework file references its values
-
-Read `org-config.yaml` at the workspace repo root before anything else. The framework ships with no org-specific values baked in; instead, files refer to org values via angle-bracketed tokens that map to keys in `org-config.yaml`:
-
-| Token | Key in `org-config.yaml` |
-| --- | --- |
-| `<ORG_NAME>` | `org_name` |
-| `<ORG_SHORT_NAME>` | `org_short_name` |
-| `<ORG_SLUG>` | `org_slug` |
-| `<org_slug>` (lowercase) | `org_slug_lower` |
-| `<ORG_REPO_URL>` | `org_repo_url` |
-| `<GITHUB_ORG>` | `github_org` |
-| `<WORKSPACE_REPO>` | `workspace_repo` |
-| `<DEFAULT_BRANCH>` | `default_branch` |
-| `<DEFAULT_CODE_BRANCH>` | `default_code_branch` |
-| `<AGENT_WORK_ROOT>` | `agent_work_root` |
-| `<POLICY_OWNER_EMAIL>` | `policy_owner_email` |
-| `<POLICY_OWNER_GITHUB>` | `policy_owner_github` |
-| `<LEGAL_OWNER_GITHUB>` etc. | `legal_owner_github`, `infra_owner_github`, `system_arch_owner_github`, `data_arch_owner_github` |
-| `<POLICY_EFFECTIVE_DATE>` | `policy_effective_date` |
-
-Tokens like `<PROJECT_ID>`, `<repo-name>`, `<your-gh-login>` are per-session values you'll discover from the current branch, `registry.yaml`, and `gh api user`.
-
-If `org-config.yaml` has empty values (`org_name: ""`), the workspace is still in TEMPLATE state. Hard-stop and tell the human to run `./setup.sh`.
-
-## 2. Load four knowledge layers — fresh every session
-
-Read these in priority order (highest first). Never use cached layers from a prior session:
-
-1. **Org-wide knowledge** — `knowledge/` in this repo, from the `<DEFAULT_BRANCH>` branch.
-2. **Active project** — `projects/<PROJECT_ID>/knowledge/` plus the project's own entrypoint at `projects/<PROJECT_ID>/agent.md`. To determine the active `PROJECT_ID`: check `registry.yaml` for entries with `status: active`, and check the current git branch (project branches are named `brnch-NNN-<slug>`).
-3. **Repo-local** — `<repo>/knowledge/` for each linked code repo at `$AGENT_WORK_ROOT/<PROJECT_ID>/<repo-name>/`.
-4. **Your developer preferences** — `$AGENT_WORK_ROOT/preferences/<your-gh-login>.md`. Run `gh api user --jq .login` to determine your handle; load **only** your file. Other files in that directory belong to other developers — do not read them.
-
-Higher layers always win. Developer preferences cannot override repo-local or org-wide knowledge.
-
-## 3. Verify project state (C01 — hard stops)
-
-If a project is active:
-
-- Confirm you are authorized: you have **write access to the project's linked GitHub Project** (the authorization source of truth — an owner grants it via `./prj manage assign`). `assigned_to` in `project.yaml` is a display/audit cache, **not** the gate. When on a task sub-branch (`brnch-NNN-<slug>/<task-slug>`), confirm that sub-branch's assignee is you.
-- `project.yaml`'s `status` must be `active`.
-- Read `projects/<PROJECT_ID>/knowledge/todo.md` and surface its `## Open` items to the developer before planning new work.
-
-If any of these can't be verified, hard-stop and surface to the human. Do not commit anything.
-
-## 4. What's writable, what's not
-
-During an active project:
-
-- ✅ Writable: `projects/<PROJECT_ID>/` (workspace repo) and code on the project branch in cloned repos under `$AGENT_WORK_ROOT/<PROJECT_ID>/`.
-- ❌ Read-only: `<WORKSPACE_REPO>/knowledge/` — never edit during an active project.
-- ❌ Never hand-manage task state — tasks are GitHub Issues on the board (open = active, closed = done); create with `./prj task`, land with `./prj merge`.
-- ❌ Don't create GitHub Issues unilaterally — those represent business intent that humans add to the GitHub Project board.
-
-## 5. Where work happens
-
-- Code repos are cloned at `$AGENT_WORK_ROOT/<PROJECT_ID>/<repo-name>/`, each on the project branch.
-- Code changes go in those cloned repos — **NOT** in the workspace repo's tree.
-- Project metadata (knowledge, decisions, to-dos) goes in `projects/<PROJECT_ID>/` in the workspace repo.
-
-## 6. During work
-
-- Capture decisions, exceptions, and policy notes in `projects/<PROJECT_ID>/knowledge/` as you make them — not at session end.
-- **Draw, don't just describe.** When the knowledge you're capturing has a flow, architecture, sequence, state machine, or relationship, author it as a **Mermaid diagram (text, never an image — POL-414)** instead of prose. One artifact serves both readers: it renders as a picture for humans and stays ~tens of diffable, RAG-indexable lines for agents and PR review. Default to a diagram for anything structural; reach for `flowchart`/`sequenceDiagram`/`stateDiagram`/`erDiagram`/`C4Context` as fits.
-- Capture intermediate to-dos in `projects/<PROJECT_ID>/knowledge/todo.md` under `## Open` as they arise.
-- When an item from `todo.md` is resolved, move it to `## Done` with a short note (commit SHA, PR link, or one-line outcome).
-
----
-
-For the canonical, full version of this protocol and the policy that governs it:
-
-- **`docs/DEVELOPER_GUIDE.md`** — step-by-step session walkthrough with example prompts.
-- **`knowledge/policies/agentic-development-policy.md`** — full policy text. POL-113 through POL-171 govern session protocol.
-
-Per-project specifics (the actual `<PROJECT_ID>`, paths, GitHub Project URL, etc.) are filled in at `projects/<PROJECT_ID>/agent.md` once the project is seeded — that file is your project-specific entrypoint.