From c5d9273abb9dea52a8946dcd77727681dde74c3f Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 15:39:52 +0530
Subject: [PATCH 01/13] chore: add repository foundation

---
 .github/ISSUE_TEMPLATE/bug.yml    | 44 +++++++++++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/config.yml |  5 ++++
 .github/ISSUE_TEMPLATE/rfc.yml    | 44 +++++++++++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/task.yml   | 44 +++++++++++++++++++++++++++++++
 .github/PULL_REQUEST_TEMPLATE.md  | 20 ++++++++++++++
 .github/workflows/guardrails.yml  | 21 +++++++++++++++
 CONTRIBUTING.md                   | 42 +++++++++++++++++++++++++++++
 LICENSES.md                       |  8 ++++++
 README.md                         | 10 +++++++
 SECURITY.md                       |  9 +++++++
 hk.pkl                            | 23 ++++++++++++++++
 mise.toml                         | 29 ++++++++++++++++++++
 renovate.json                     |  7 +++++
 13 files changed, 306 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug.yml
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/rfc.yml
 create mode 100644 .github/ISSUE_TEMPLATE/task.yml
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/workflows/guardrails.yml
 create mode 100644 CONTRIBUTING.md
 create mode 100644 LICENSES.md
 create mode 100644 SECURITY.md
 create mode 100644 hk.pkl
 create mode 100644 mise.toml
 create mode 100644 renovate.json

diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
new file mode 100644
index 0000000..4cc977f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,44 @@
+name: Bug report
+description: Report behavior that is broken, incorrect, or unexpectedly failing.
+title: "fix: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for reproducible defects. Keep secrets, real local session data, and private logs out of public issues.
+  - type: textarea
+    id: current-behavior
+    attributes:
+      label: Current behavior
+      description: What happens now?
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: What should happen instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Minimal steps a maintainer can run to reproduce the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, runtime versions, branch/commit, and affected package or command.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: Observable outcomes that prove the bug is fixed.
+    validations:
+      required: false
+
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..91178ef
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Private security report
+    url: https://github.com/agent-trail/cli/security/advisories/new
+    about: Report vulnerabilities privately instead of opening a public issue.
diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
new file mode 100644
index 0000000..c50a6b4
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/rfc.yml
@@ -0,0 +1,44 @@
+name: RFC / spec decision
+description: Propose a load-bearing Agent Trail format, schema, validation, package layout, or architecture decision.
+title: "rfc: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this before changing load-bearing shape such as normative format or schema semantics, validation terminology or behavior, versioning, hash semantics, artifact identity, package layout, durable architecture, or public URL shape.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or decision
+      description: What decision needs to be made, and why now?
+    validations:
+      required: true
+  - type: textarea
+    id: affected-surface
+    attributes:
+      label: Affected contract surface
+      description: Name the spec section, schema path, package API, CLI behavior, docs, ADRs, fixtures, or public URLs affected.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: State the exact rule or direction to adopt.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: List plausible options and tradeoffs.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: Observable outcomes that prove the decision has been implemented.
+    validations:
+      required: true
+
diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml
new file mode 100644
index 0000000..8d19bdf
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/task.yml
@@ -0,0 +1,44 @@
+name: Task or feature
+description: Request a scoped implementation task, feature, refactor, or docs update.
+title: "feat: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for work that should be implementable by a human or coding agent from the issue alone.
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+      description: What should be true when this is done?
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope
+      description: What is included?
+    validations:
+      required: true
+  - type: textarea
+    id: non-goals
+    attributes:
+      label: Non-goals
+      description: What should not be changed or added?
+    validations:
+      required: false
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: Observable outcomes that prove the task is complete.
+    validations:
+      required: true
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification
+      description: Commands or checks that should pass.
+    validations:
+      required: true
+
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..e320561
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,20 @@
+## Summary
+
+- 
+
+## Public Impact
+
+- [ ] No public contract change
+- [ ] Spec or schema change
+- [ ] Public package API change
+- [ ] CLI behavior change
+- [ ] Public URL or docs behavior change
+
+## Verification
+
+- 
+
+## Reviewer Notes
+
+- 
+
diff --git a/.github/workflows/guardrails.yml b/.github/workflows/guardrails.yml
new file mode 100644
index 0000000..6971b75
--- /dev/null
+++ b/.github/workflows/guardrails.yml
@@ -0,0 +1,21 @@
+name: guardrails
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  guardrails:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - uses: jdx/mise-action@5228313ee0372e111a38da051671ca30fc5a96db # v3
+      - name: Run repository checks
+        run: mise run check
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..03233d5
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,42 @@
+# Contributing
+
+Agent Trail work is tracked in Linear and implemented through pull requests.
+
+## Workflow
+
+- Start from a Linear issue or accepted maintainer direction.
+- Keep changes scoped to the active issue.
+- Use Conventional Commit subjects for commits and pull request titles.
+- Do not include agent attribution in commits, pull request bodies, generated docs, or code comments.
+- Do not commit real local sessions, secrets, credentials, tokens, private logs, or unredacted user data.
+
+## Local Setup
+
+Install tools and hooks:
+
+```sh
+mise install
+mise run hooks:install
+```
+
+Common tasks:
+
+```sh
+mise run check
+mise run lint
+mise run test
+```
+
+`mise` is the repo entrypoint for tools and tasks. `hk` owns Git hooks and project lint gates.
+
+## Pull Requests
+
+Before opening a pull request:
+
+- Run `mise run check`.
+- Link the Linear issue.
+- State public spec, schema, package API, CLI, or URL impact.
+- Include exact verification commands and results.
+
+Pull requests are squash-merged. Keep branches narrow and delete them after merge.
+
diff --git a/LICENSES.md b/LICENSES.md
new file mode 100644
index 0000000..0812ad4
--- /dev/null
+++ b/LICENSES.md
@@ -0,0 +1,8 @@
+# Licensing
+
+This repository contains the Agent Trail command-line implementation.
+
+Unless otherwise noted, source code, package docs, tests, and implementation documentation in this repository are licensed under MIT.
+
+The Agent Trail format contract lives in `agent-trail/spec` and is Apache-2.0 unless that repository says otherwise.
+
diff --git a/README.md b/README.md
index 802bf0b..5bb94e1 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,12 @@
 # cli
 Agent Trail command-line interface.
+
+## Development
+
+```sh
+mise install
+mise run hooks:install
+mise run check
+```
+
+See `CONTRIBUTING.md` for workflow and PR expectations.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..b015641
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,9 @@
+# Security
+
+Do not open public issues for vulnerabilities.
+
+Use GitHub private vulnerability reporting:
+
+https://github.com/agent-trail/cli/security/advisories/new
+
+Do not include secrets, credentials, private local paths, or unredacted session data in reports unless they are necessary to reproduce the issue.
diff --git a/hk.pkl b/hk.pkl
new file mode 100644
index 0000000..b69058f
--- /dev/null
+++ b/hk.pkl
@@ -0,0 +1,23 @@
+amends "package://github.com/jdx/hk/releases/download/v1.47.0/hk@1.47.0#/Config.pkl"
+import "package://github.com/jdx/hk/releases/download/v1.47.0/hk@1.47.0#/Builtins.pkl"
+
+local linters = new Mapping {
+  ["actionlint"] = Builtins.actionlint
+  ["zizmor"] {
+    glob = List(".github/workflows/*.yml", ".github/workflows/*.yaml")
+    check = "zizmor .github/workflows"
+  }
+}
+
+hooks {
+  ["pre-commit"] {
+    steps = linters
+  }
+  ["pre-push"] {
+    steps = linters
+  }
+  ["check"] {
+    steps = linters
+  }
+}
+
diff --git a/mise.toml b/mise.toml
new file mode 100644
index 0000000..06b3c38
--- /dev/null
+++ b/mise.toml
@@ -0,0 +1,29 @@
+[tools]
+"aqua:jdx/hk" = "1.47.0"
+"aqua:rhysd/actionlint" = "1.7.12"
+"aqua:zizmorcore/zizmor" = "1.25.2"
+
+[tasks.setup]
+description = "Install tools and configure Git hooks"
+depends = ["hooks:install"]
+
+[tasks."hooks:install"]
+description = "Install hk Git hooks"
+run = "hk install"
+
+[tasks.check]
+description = "Run all repository checks"
+depends = ["lint", "test"]
+
+[tasks.lint]
+description = "Run project lint gates"
+run = "hk check"
+
+[tasks.test]
+description = "Run tests for this repository"
+run = "echo 'No tests configured yet.'"
+
+[tasks."check:actions"]
+description = "Validate GitHub Actions workflows"
+run = "actionlint && zizmor .github/workflows"
+
diff --git a/renovate.json b/renovate.json
new file mode 100644
index 0000000..057c514
--- /dev/null
+++ b/renovate.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "labels": ["dependencies"],
+  "timezone": "Asia/Kolkata"
+}
+

From a70daf27f7db84292718575824cbce0b47cdae31 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 15:56:06 +0530
Subject: [PATCH 02/13] chore: address review feedback

---
 .github/PULL_REQUEST_TEMPLATE.md | 3 ++-
 .github/workflows/guardrails.yml | 4 ++++
 CONTRIBUTING.md                  | 4 +---
 README.md                        | 3 +--
 mise.toml                        | 3 +--
 renovate.json                    | 4 +---
 6 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index e320561..656a954 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,3 +1,5 @@
+# Pull Request
+
 ## Summary
 
 - 
@@ -17,4 +19,3 @@
 ## Reviewer Notes
 
 - 
-
diff --git a/.github/workflows/guardrails.yml b/.github/workflows/guardrails.yml
index 6971b75..8e40a50 100644
--- a/.github/workflows/guardrails.yml
+++ b/.github/workflows/guardrails.yml
@@ -9,6 +9,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   guardrails:
     runs-on: ubuntu-latest
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 03233d5..28d57b1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,8 +15,7 @@ Agent Trail work is tracked in Linear and implemented through pull requests.
 Install tools and hooks:
 
 ```sh
-mise install
-mise run hooks:install
+mise run setup
 ```
 
 Common tasks:
@@ -39,4 +38,3 @@ Before opening a pull request:
 - Include exact verification commands and results.
 
 Pull requests are squash-merged. Keep branches narrow and delete them after merge.
-
diff --git a/README.md b/README.md
index 5bb94e1..cd730f4 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,7 @@ Agent Trail command-line interface.
 ## Development
 
 ```sh
-mise install
-mise run hooks:install
+mise run setup
 mise run check
 ```
 
diff --git a/mise.toml b/mise.toml
index 06b3c38..40da695 100644
--- a/mise.toml
+++ b/mise.toml
@@ -25,5 +25,4 @@ run = "echo 'No tests configured yet.'"
 
 [tasks."check:actions"]
 description = "Validate GitHub Actions workflows"
-run = "actionlint && zizmor .github/workflows"
-
+run = "if [ -d .github/workflows ]; then actionlint && zizmor .github/workflows; else echo 'No GitHub Actions workflows configured.'; fi"
diff --git a/renovate.json b/renovate.json
index 057c514..6dc7957 100644
--- a/renovate.json
+++ b/renovate.json
@@ -1,7 +1,5 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": ["config:recommended"],
-  "labels": ["dependencies"],
-  "timezone": "Asia/Kolkata"
+  "labels": ["dependencies"]
 }
-

From 9f96e67d7bebd18337d63129b66be6a479361896 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 15:57:44 +0530
Subject: [PATCH 03/13] chore: normalize issue templates

---
 .github/ISSUE_TEMPLATE/bug.yml  | 1 -
 .github/ISSUE_TEMPLATE/rfc.yml  | 1 -
 .github/ISSUE_TEMPLATE/task.yml | 1 -
 3 files changed, 3 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
index 4cc977f..d102922 100644
--- a/.github/ISSUE_TEMPLATE/bug.yml
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -41,4 +41,3 @@ body:
       description: Observable outcomes that prove the bug is fixed.
     validations:
       required: false
-
diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
index c50a6b4..9ea56e9 100644
--- a/.github/ISSUE_TEMPLATE/rfc.yml
+++ b/.github/ISSUE_TEMPLATE/rfc.yml
@@ -41,4 +41,3 @@ body:
       description: Observable outcomes that prove the decision has been implemented.
     validations:
       required: true
-
diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml
index 8d19bdf..11725e0 100644
--- a/.github/ISSUE_TEMPLATE/task.yml
+++ b/.github/ISSUE_TEMPLATE/task.yml
@@ -41,4 +41,3 @@ body:
       description: Commands or checks that should pass.
     validations:
       required: true
-

From 8fbb63cd02ded15fff1eb5450ab2ac5eea9f721e Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 16:14:16 +0530
Subject: [PATCH 04/13] docs: add agent instructions

---
 AGENTS.md | 24 ++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 25 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d57df93
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,24 @@
+# Agent Instructions
+
+This repo owns the Agent Trail CLI and source-agent adapter behavior compiled into the CLI.
+
+## Workflow
+
+- Start from the linked Linear issue or maintainer direction.
+- Keep changes scoped to CLI commands, adapter behavior, packaging, or CLI docs.
+- Do not change the Agent Trail file format contract here; make spec changes in the spec repo.
+- Do not commit real local sessions, secrets, credentials, private logs, or unredacted user data.
+- Do not include agent attribution in commits, pull request bodies, generated docs, or code comments.
+
+## Commands
+
+- Use `mise run setup` for local tool and hook setup.
+- Use `mise run check` before opening or updating a pull request.
+- Use `mise run check:actions` after editing GitHub Actions workflows.
+
+## Pull Requests
+
+- Use `.github/PULL_REQUEST_TEMPLATE.md`.
+- Link the Linear issue.
+- State CLI behavior, adapter behavior, or packaging impact.
+- Include exact verification commands and results.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file

From 59e9b06a9b5db531969e7b43882114d32417e65a Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 18:22:34 +0530
Subject: [PATCH 05/13] docs: trim agent instructions

---
 AGENTS.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index d57df93..b819c1c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,6 @@ This repo owns the Agent Trail CLI and source-agent adapter behavior compiled in
 - Keep changes scoped to CLI commands, adapter behavior, packaging, or CLI docs.
 - Do not change the Agent Trail file format contract here; make spec changes in the spec repo.
 - Do not commit real local sessions, secrets, credentials, private logs, or unredacted user data.
-- Do not include agent attribution in commits, pull request bodies, generated docs, or code comments.
 
 ## Commands
 

From d6c3f3e0b1809ed4aca5166ca5df74e5c2a1b898 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 18:32:38 +0530
Subject: [PATCH 06/13] chore: pin bun runtime

---
 mise.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mise.toml b/mise.toml
index 40da695..78fd024 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,4 +1,5 @@
 [tools]
+bun = "1.2.17"
 "aqua:jdx/hk" = "1.47.0"
 "aqua:rhysd/actionlint" = "1.7.12"
 "aqua:zizmorcore/zizmor" = "1.25.2"

From c2bcf43172cb71bb345a427ec161cf9edea46e5f Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 18:53:15 +0530
Subject: [PATCH 07/13] chore: update tool pins

---
 .github/workflows/guardrails.yml | 4 ++--
 hk.pkl                           | 5 ++---
 mise.toml                        | 4 ++--
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/guardrails.yml b/.github/workflows/guardrails.yml
index 8e40a50..a3487eb 100644
--- a/.github/workflows/guardrails.yml
+++ b/.github/workflows/guardrails.yml
@@ -17,9 +17,9 @@ jobs:
   guardrails:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
         with:
           persist-credentials: false
-      - uses: jdx/mise-action@5228313ee0372e111a38da051671ca30fc5a96db # v3
+      - uses: jdx/mise-action@dba19683ed58901619b14f395a24841710cb4925 # v4.1.0
       - name: Run repository checks
         run: mise run check
diff --git a/hk.pkl b/hk.pkl
index b69058f..68e6af5 100644
--- a/hk.pkl
+++ b/hk.pkl
@@ -1,5 +1,5 @@
-amends "package://github.com/jdx/hk/releases/download/v1.47.0/hk@1.47.0#/Config.pkl"
-import "package://github.com/jdx/hk/releases/download/v1.47.0/hk@1.47.0#/Builtins.pkl"
+amends "package://github.com/jdx/hk/releases/download/v1.48.0/hk@1.48.0#/Config.pkl"
+import "package://github.com/jdx/hk/releases/download/v1.48.0/hk@1.48.0#/Builtins.pkl"
 
 local linters = new Mapping {
   ["actionlint"] = Builtins.actionlint
@@ -20,4 +20,3 @@ hooks {
     steps = linters
   }
 }
-
diff --git a/mise.toml b/mise.toml
index 78fd024..e8025ff 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,6 +1,6 @@
 [tools]
-bun = "1.2.17"
-"aqua:jdx/hk" = "1.47.0"
+bun = "1.3.14"
+"aqua:jdx/hk" = "1.48.0"
 "aqua:rhysd/actionlint" = "1.7.12"
 "aqua:zizmorcore/zizmor" = "1.25.2"
 

From cba842325f0c7fc9678d91a6bfef35bd09d98f16 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 18:56:23 +0530
Subject: [PATCH 08/13] docs: clarify contributor guidance

---
 AGENTS.md       |  4 ++++
 CONTRIBUTING.md | 20 +++++++++++---------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b819c1c..1f41222 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,10 @@ This repo owns the Agent Trail CLI and source-agent adapter behavior compiled in
 - Use `mise run check` before opening or updating a pull request.
 - Use `mise run check:actions` after editing GitHub Actions workflows.
 
+## Dependencies and Tools
+
+- Before introducing a package, tool, or GitHub Action, check the latest upstream stable version and use it unless there is a documented reason not to.
+
 ## Pull Requests
 
 - Use `.github/PULL_REQUEST_TEMPLATE.md`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 28d57b1..80ee50c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,14 +1,12 @@
 # Contributing
 
-Agent Trail work is tracked in Linear and implemented through pull requests.
+Thanks for helping improve Agent Trail.
 
-## Workflow
+## Before You Start
 
-- Start from a Linear issue or accepted maintainer direction.
-- Keep changes scoped to the active issue.
-- Use Conventional Commit subjects for commits and pull request titles.
-- Do not include agent attribution in commits, pull request bodies, generated docs, or code comments.
-- Do not commit real local sessions, secrets, credentials, tokens, private logs, or unredacted user data.
+- Open or pick up a Linear issue before starting larger changes.
+- Keep pull requests focused on one problem.
+- Avoid committing real local sessions, secrets, credentials, tokens, private logs, or unredacted user data.
 
 ## Local Setup
 
@@ -26,7 +24,11 @@ mise run lint
 mise run test
 ```
 
-`mise` is the repo entrypoint for tools and tasks. `hk` owns Git hooks and project lint gates.
+`mise` installs repo tools and runs tasks. `hk` owns local Git hooks.
+
+## Dependencies and Tools
+
+When adding a package, tool, or GitHub Action, check the latest stable upstream version first. Use the latest version by default; if you pin an older version, explain why in the pull request.
 
 ## Pull Requests
 
@@ -34,7 +36,7 @@ Before opening a pull request:
 
 - Run `mise run check`.
 - Link the Linear issue.
-- State public spec, schema, package API, CLI, or URL impact.
+- Summarize CLI behavior, adapter behavior, or packaging impact.
 - Include exact verification commands and results.
 
 Pull requests are squash-merged. Keep branches narrow and delete them after merge.

From d0c00cfa3c474e2c72d57e306f9b0a852ae6fb17 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 19:03:15 +0530
Subject: [PATCH 09/13] docs: add repo branding and license

---
 LICENSE     | 9 +++++++++
 LICENSES.md | 8 --------
 README.md   | 9 +++++++--
 3 files changed, 16 insertions(+), 10 deletions(-)
 create mode 100644 LICENSE
 delete mode 100644 LICENSES.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..700eaf7
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Agent Trail contributors
+
+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.
diff --git a/LICENSES.md b/LICENSES.md
deleted file mode 100644
index 0812ad4..0000000
--- a/LICENSES.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Licensing
-
-This repository contains the Agent Trail command-line implementation.
-
-Unless otherwise noted, source code, package docs, tests, and implementation documentation in this repository are licensed under MIT.
-
-The Agent Trail format contract lives in `agent-trail/spec` and is Apache-2.0 unless that repository says otherwise.
-
diff --git a/README.md b/README.md
index cd730f4..27ead37 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
-# cli
-Agent Trail command-line interface.
+# Agent Trail CLI
+
+Command-line tools for discovering, validating, loading, sharing, and exporting Agent Trail files.
 
 ## Development
 
@@ -9,3 +10,7 @@ mise run check
 ```
 
 See `CONTRIBUTING.md` for workflow and PR expectations.
+
+## License
+
+MIT. See `LICENSE`.

From 1584f7c2c4e098d5e824d06ecebf73d36b4c2168 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 19:12:48 +0530
Subject: [PATCH 10/13] docs: link related repositories

---
 README.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/README.md b/README.md
index 27ead37..c01b056 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,15 @@
 
 Command-line tools for discovering, validating, loading, sharing, and exporting Agent Trail files.
 
+## Related Repositories
+
+Agent Trail is split across focused repositories:
+
+- [agent-trail/spec](https://github.com/agent-trail/spec) - format contract, JSON Schema, fixtures, and format ADRs.
+- [agent-trail/typescript-sdk](https://github.com/agent-trail/typescript-sdk) - TypeScript packages for Agent Trail files.
+- [agent-trail/cli](https://github.com/agent-trail/cli) - command-line tools for Agent Trail workflows.
+- [agent-trail/web](https://github.com/agent-trail/web) - docs site and shared trail web viewer.
+
 ## Development
 
 ```sh

From 7bd0fa6ace8f09384ec8ca0bf9f3aeb71639942f Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 21:04:36 +0530
Subject: [PATCH 11/13] docs: adapt contributing for external contributors

---
 CONTRIBUTING.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 80ee50c..6e422d5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ Thanks for helping improve Agent Trail.
 
 ## Before You Start
 
-- Open or pick up a Linear issue before starting larger changes.
+- For larger changes, open a GitHub issue or discussion first so maintainers can agree on scope.
 - Keep pull requests focused on one problem.
 - Avoid committing real local sessions, secrets, credentials, tokens, private logs, or unredacted user data.
 
@@ -35,7 +35,7 @@ When adding a package, tool, or GitHub Action, check the latest stable upstream
 Before opening a pull request:
 
 - Run `mise run check`.
-- Link the Linear issue.
+- Link the relevant GitHub issue or discussion, if one exists.
 - Summarize CLI behavior, adapter behavior, or packaging impact.
 - Include exact verification commands and results.
 

From 4d254cb52f92027b64af355ac76278f487716e3c Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 21:14:12 +0530
Subject: [PATCH 12/13] docs: remove non-spec rfc template

---
 .github/ISSUE_TEMPLATE/rfc.yml | 43 ----------------------------------
 1 file changed, 43 deletions(-)
 delete mode 100644 .github/ISSUE_TEMPLATE/rfc.yml

diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
deleted file mode 100644
index 9ea56e9..0000000
--- a/.github/ISSUE_TEMPLATE/rfc.yml
+++ /dev/null
@@ -1,43 +0,0 @@
-name: RFC / spec decision
-description: Propose a load-bearing Agent Trail format, schema, validation, package layout, or architecture decision.
-title: "rfc: "
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Use this before changing load-bearing shape such as normative format or schema semantics, validation terminology or behavior, versioning, hash semantics, artifact identity, package layout, durable architecture, or public URL shape.
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem or decision
-      description: What decision needs to be made, and why now?
-    validations:
-      required: true
-  - type: textarea
-    id: affected-surface
-    attributes:
-      label: Affected contract surface
-      description: Name the spec section, schema path, package API, CLI behavior, docs, ADRs, fixtures, or public URLs affected.
-    validations:
-      required: true
-  - type: textarea
-    id: proposal
-    attributes:
-      label: Proposal
-      description: State the exact rule or direction to adopt.
-    validations:
-      required: true
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives considered
-      description: List plausible options and tradeoffs.
-    validations:
-      required: true
-  - type: textarea
-    id: acceptance-criteria
-    attributes:
-      label: Acceptance criteria
-      description: Observable outcomes that prove the decision has been implemented.
-    validations:
-      required: true

From 5f0498d86578b13780d7c5e3b1445f34abf6bbac Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 21:27:06 +0530
Subject: [PATCH 13/13] ci: include workflow checks

---
 .github/PULL_REQUEST_TEMPLATE.md | 8 ++++++++
 mise.toml                        | 2 +-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 656a954..9ae7d85 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,6 +4,10 @@
 
 - 
 
+## Related Issue
+
+- 
+
 ## Public Impact
 
 - [ ] No public contract change
@@ -12,6 +16,10 @@
 - [ ] CLI behavior change
 - [ ] Public URL or docs behavior change
 
+Impact description:
+
+- 
+
 ## Verification
 
 - 
diff --git a/mise.toml b/mise.toml
index e8025ff..372aac9 100644
--- a/mise.toml
+++ b/mise.toml
@@ -14,7 +14,7 @@ run = "hk install"
 
 [tasks.check]
 description = "Run all repository checks"
-depends = ["lint", "test"]
+depends = ["lint", "test", "check:actions"]
 
 [tasks.lint]
 description = "Run project lint gates"