Build portable agent-home v0.1.0

.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "agent-home",
+  "description": "Portable agent-home skills and task operations.",
+  "owner": {
+    "name": "elix1er",
+    "url": "https://github.com/elix1er"
+  },
+  "plugins": [
+    {
+      "name": "agent-home",
+      "source": "./",
+      "description": "Operate a private GitHub Issues task ledger.",
+      "version": "0.1.0",
+      "author": {
+        "name": "elix1er"
+      },
+      "homepage": "https://github.com/elix1er/agent-home#readme",
+      "repository": "https://github.com/elix1er/agent-home",
+      "license": "Apache-2.0",
+      "category": "productivity",
+      "tags": ["agent", "tasks", "github", "mcp"]
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "agent-home",
+  "version": "0.1.0",
+  "description": "Portable, auditable task home for one agent.",
+  "author": {
+    "name": "elix1er",
+    "url": "https://github.com/elix1er"
+  },
+  "homepage": "https://github.com/elix1er/agent-home#readme",
+  "repository": "https://github.com/elix1er/agent-home",
+  "license": "Apache-2.0",
+  "keywords": ["agent", "tasks", "github", "mcp", "skills"]
+}

.codex-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "agent-home",
+  "version": "0.1.0",
+  "description": "Portable, auditable task home for one agent.",
+  "author": {
+    "name": "elix1er",
+    "url": "https://github.com/elix1er"
+  },
+  "homepage": "https://github.com/elix1er/agent-home#readme",
+  "repository": "https://github.com/elix1er/agent-home",
+  "license": "Apache-2.0",
+  "keywords": ["agent", "tasks", "github", "mcp", "skills"],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Agent Home",
+    "shortDescription": "Operate a private agent task ledger.",
+    "longDescription": "Create, claim, update, block, and complete auditable agent tasks in a private GitHub repository.",
+    "developerName": "elix1er",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://github.com/elix1er/agent-home",
+    "defaultPrompt": [
+      "Add this task to my agent home.",
+      "What should you work on next?",
+      "Show my blocked agent tasks."
+    ]
+  }
+}

.env.example

@@ -0,0 +1,16 @@
+# Public URL of this deployment, without a trailing slash.
+AGENT_HOME_URL=https://your-agent-home.vercel.app
+
+# Auth0 API settings. Keep actual values only in Vercel/local environment.
+AUTH0_ISSUER=https://your-tenant.eu.auth0.com/
+AUTH0_AUDIENCE=https://your-agent-home.vercel.app/api/mcp
+AUTH0_GITHUB_CLAIM=https://agent-home.dev/github_login
+
+# Option A: fine-grained token scoped to this one private repo.
+GITHUB_TOKEN=
+
+# Option B (preferred for durable hosting): GitHub App credentials. Use either
+# this complete group or GITHUB_TOKEN, never both. Preserve private-key newlines.
+GITHUB_APP_ID=
+GITHUB_APP_INSTALLATION_ID=
+GITHUB_APP_PRIVATE_KEY=

.github/ISSUE_TEMPLATE/agent-task.yml

@@ -0,0 +1,58 @@
+name: Agent task
+description: Add one outcome to the agent-home task ledger
+title: "[Task] "
+labels:
+  - "agent:inbox"
+body:
+  - type: markdown
+    attributes:
+      value: "One issue is one reviewable outcome. Never include credentials or private exports."
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+      description: What observable result should exist?
+      placeholder: Prepare a reviewable release checklist for v0.2.0.
+    validations:
+      required: true
+  - type: textarea
+    id: constraints
+    attributes:
+      label: Constraints
+      description: Scope, safety rules, timing, and explicit exclusions.
+      placeholder: Do not deploy or merge. Keep it provider-neutral.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Use a checkbox for each observable completion condition.
+      placeholder: "- [ ] Checklist is linked from the release issue"
+    validations:
+      required: true
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Priority
+      options:
+        - normal
+        - high
+        - critical
+        - low
+      default: 0
+    validations:
+      required: true
+  - type: checkboxes
+    id: capabilities
+    attributes:
+      label: Enabled capability grants
+      description: These narrow the instance allowlist; they never expand agent-home.yml.
+      options:
+        - label: "`github.issues.write`"
+          required: true
+        - label: "`github.pull_requests.write`"
+        - label: "`github.contents.write`"
+        - label: "`vercel.deploy`"
+        - label: "`browser.use`"
+        - label: "`computer.use`"

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Private security report
+    url: https://github.com/elix1er/agent-home/security/advisories/new
+    about: Report authentication, authorization, or credential issues privately.

.github/workflows/hosted-smoke.yml

@@ -0,0 +1,51 @@
+name: Hosted MCP smoke
+
+on:
+  workflow_dispatch:
+    inputs:
+      mcp_url:
+        description: Full private deployment URL ending in /api/mcp
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  inspect:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.19
+      - name: Verify protected resource metadata
+        env:
+          MCP_URL: ${{ inputs.mcp_url }}
+        run: |
+          base_url="${MCP_URL%/api/mcp}"
+          curl --fail --silent --show-error "${base_url}/.well-known/oauth-protected-resource" > /tmp/resource.json
+          node -e 'const m=require("/tmp/resource.json"); if (!m.authorization_servers?.length || !m.scopes_supported?.includes("tasks:write")) process.exit(1)'
+      - name: Reject unauthenticated MCP request
+        env:
+          MCP_URL: ${{ inputs.mcp_url }}
+        run: |
+          code=$(curl --silent --output /tmp/unauthenticated.json --dump-header /tmp/unauthenticated.headers --write-out '%{http_code}' \
+            -H 'content-type: application/json' \
+            --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"agent-home-smoke","version":"0.1.0"}}}' \
+            "${MCP_URL}")
+          test "${code}" = "401"
+          grep -qi '^www-authenticate: Bearer' /tmp/unauthenticated.headers
+      - name: Inspect authenticated tool contract
+        env:
+          MCP_URL: ${{ inputs.mcp_url }}
+          MCP_SMOKE_BEARER_TOKEN: ${{ secrets.MCP_SMOKE_BEARER_TOKEN }}
+        run: |
+          test -n "${MCP_SMOKE_BEARER_TOKEN}"
+          npx --yes @modelcontextprotocol/inspector@2.2.0 --cli \
+            --transport http \
+            --server-url "${MCP_URL}" \
+            --header "Authorization: Bearer ${MCP_SMOKE_BEARER_TOKEN}" \
+            --method tools/list \
+            --format json > /tmp/tools.json
+          node scripts/verify-inspector-output.mjs /tmp/tools.json

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm audit --audit-level=moderate
+      - run: npm run check
+      - name: Verify tag matches package version
+        run: test "${GITHUB_REF_NAME}" = "v$(node -p 'require("./package.json").version')"
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${GITHUB_REF_NAME}" --verify-tag --generate-notes --title "agent-home ${GITHUB_REF_NAME}"

.github/workflows/setup-labels.yml

@@ -0,0 +1,41 @@
+name: Set up agent-home labels
+
+on:
+  workflow_dispatch:
+
+permissions:
+  issues: write
+
+jobs:
+  labels:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create or update task state labels
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const labels = [
+              ['agent:inbox', 'D4C5F9', 'Actionable agent task'],
+              ['agent:active', '1D76DB', 'Task currently claimed by an agent'],
+              ['agent:blocked', 'D93F0B', 'Task needs a decision or capability'],
+              ['agent:done', '0E8A16', 'Task completed with evidence'],
+            ];
+
+            for (const [name, color, description] of labels) {
+              try {
+                await github.rest.issues.updateLabel({
+                  ...context.repo,
+                  name,
+                  color,
+                  description,
+                });
+              } catch (error) {
+                if (error.status !== 404) throw error;
+                await github.rest.issues.createLabel({
+                  ...context.repo,
+                  name,
+                  color,
+                  description,
+                });
+              }
+            }

.github/workflows/validate.yml

@@ -0,0 +1,34 @@
+name: Validate
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm audit --audit-level=moderate
+      - run: npm run check

.github/workflows/weekly-improvement.yml

@@ -20,6 +20,18 @@ jobs:
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const title = 'Weekly agent-home review';
+            try {
+              await github.rest.issues.getLabel({ owner, repo, name: 'agent:inbox' });
+            } catch (error) {
+              if (error.status !== 404) throw error;
+              await github.rest.issues.createLabel({
+                owner,
+                repo,
+                name: 'agent:inbox',
+                color: 'D4C5F9',
+                description: 'Actionable agent task',
+              });
+            }
             const { data: issues } = await github.rest.issues.listForRepo({
               owner,
               repo,
@@ -38,14 +50,23 @@ jobs:
               repo,
               title,
               body: [
-                'Run `automations/weekly-review.md` with your preferred agent.',
+                '## Desired outcome',
+                'Run `automations/weekly-review.md` with the preferred agent.',
+                '',
+                '## Constraints',
+                'Choose at most one genuinely useful improvement. Never auto-merge or deploy.',
+                '',
+                '## Acceptance criteria',
+                '- [ ] One useful improvement is proposed or completed, or the issue is closed with `no change`',
+                '- [ ] Repository changes use an `agent/*` branch and pull request',
                 '',
-                '- [ ] Choose at most one useful improvement',
-                '- [ ] Use an `agent/*` branch and pull request for changes',
-                '- [ ] Close this issue when reviewed',
+                '## Priority',
+                'low',
                 '',
-                'If nothing is worth changing, close with `no change`.',
+                '## Enabled capability grants',
+                '- `github.issues.write`',
               ].join('\n'),
+              labels: ['agent:inbox'],
             });
 
             core.notice(`Created review: #${issue.number}`);

.gitignore

@@ -10,6 +10,8 @@
 .codex/
 .zcode/
 node_modules/
+.next/
+*.tsbuildinfo
 .venv/
 __pycache__/
 dist/

.nvmrc

@@ -0,0 +1 @@
+20

AGENTS.md

@@ -1,13 +1,15 @@
 # Agent home
 
-Keep this repo useful, personal, and light.
+Keep this repository portable, auditable, and light.
 
-- Check what already exists before adding anything.
-- Read `identity.md`, `goal.md`, and `inbox.md` before choosing work.
-- Keep one clear current goal; move completed work into `archive/`.
-- Save only reusable skills, automation prompts, and durable context.
-- Never commit secrets, private exports, caches, or machine-local state.
-- Prefer short plain files over frameworks and dependencies.
+- Read `agent-home.yml`, `identity.md`, and `goal.md` before choosing work.
+- Treat GitHub Issues as the canonical task ledger and closed `agent:done` issues as the task archive.
+- Use exactly one state label: `agent:inbox`, `agent:active`, `agent:blocked`, or `agent:done`.
+- Act only through capabilities explicitly allowed by `agent-home.yml`; missing capability means blocked.
+- Log every task mutation with a concise issue comment containing action, result, and evidence.
+- Save only reusable skills, durable policy, identity, and long-lived learnings in Git.
+- Never commit or repeat secrets, private exports, tokens, headers, caches, or machine-local state.
+- Prefer short plain files and small dependencies over frameworks inside frameworks.
 - Use a branch and pull request; do not push directly to `main`.
-- Automations may suggest changes, but must not auto-merge, deploy, message people, rotate credentials, or delete data.
+- Never auto-merge, deploy, message people, rotate credentials, or delete data unless the current task explicitly grants the named capability and the host exposes it.
 - If there is nothing genuinely useful to improve, say `no change`.