prd.json

{
  "version": "1.0",
  "projectName": "agent-secrets",
  "description": "Agent-first CLI refresh for agent-secrets. Align with joelclaw cli-design standard: JSON-only output, HATEOAS next_actions, self-documenting root command, lease defaults to raw value, errors include fix field.",
  "stories": [
    {
      "id": "story-mlsqzwdh",
      "title": "Refactor response envelope to match cli-design standard",
      "description": "Refactor the Response struct in internal/output/output.go to match the joelclaw cli-design standard envelope:\n\n**Current:** `{success, message, data, error, exit_code, actions, update}`\n**Target:** `{ok, command, result, error: {message, code}, fix, next_actions}`\n\nChanges needed:\n1. `internal/output/output.go`: Rename `Response` fields:\n   - `Success bool` → `OK bool` (json:\"ok\")\n   - `Data interface{}` → `Result interface{}` (json:\"result,omitempty\")\n   - `Error string` → restructure to `Error *ErrorDetail` (json:\"error,omitempty\") where ErrorDetail has `Message string` + `Code string`\n   - `Actions []Action` → `NextActions []Action` (json:\"next_actions,omitempty\")\n   - Add `Command string` (json:\"command\") — the command that was run\n   - Add `Fix string` (json:\"fix,omitempty\") — plain-language fix suggestion on errors\n   - Remove `Message string` (fold into result or remove)\n   - Remove `ExitCode int` from JSON (keep for process exit only)\n   - Remove `Update *UpdateInfo` from envelope (or fold into result)\n2. Update `Action` struct: remove `Name` field, keep only `Command` and `Description` (matching standard)\n3. Update all helper functions: `Success()`, `Error()`, `ErrorMsg()`, etc. to use new shape\n4. Update `internal/output/json.go` — JSONFormatter stays the same structurally\n5. Update `internal/output/raw.go` — RawFormatter reads from `Result` instead of `Data`\n6. Update `internal/output/table.go` — TableFormatter reads new fields\n7. Update ALL command files in `cmd/secrets/` that call `output.Print()`, `output.Success()`, `output.Error()` etc:\n   - add.go, audit.go, cleanup.go, env.go, exec.go, health.go, init.go, lease.go, revoke.go, scan.go, status.go\n   - Each must pass the `command` string (e.g., \"secrets lease\", \"secrets add\")\n8. Update `internal/types/errors.go` and `internal/types/exitcodes.go` if error codes need mapping to the new `Code string` field\n\nDo NOT change the lease default behavior yet (that's a separate story). Do NOT remove output format flags yet (separate story). Just refactor the envelope shape.",
      "priority": 1,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "internal/output/output.go",
        "cmd/secrets/lease.go",
        "cmd/secrets/add.go"
      ]
    },
    {
      "id": "story-mlsr055z",
      "title": "Make lease default to raw value output",
      "description": "Change `secrets lease` to output ONLY the secret value by default (no JSON envelope). This is the #1 agent UX issue — agents always forget `--raw` and expect to get the value directly.\n\nChanges:\n1. `cmd/secrets/lease.go`:\n   - Flip the default: raw output is now default behavior\n   - Remove `--raw` flag (it's now the default)\n   - Add `--json` flag to opt INTO the full JSON envelope when needed\n   - When default (no --json): `fmt.Print(result.Value)` — just the value, no newline, perfect for `$(secrets lease name)`\n   - When `--json`: output the full HATEOAS JSON envelope with ok/command/result/next_actions\n2. Update the help text / Long description to reflect this change\n3. Update `internal/output/output.go` action helpers that reference `--raw` (like `ActionLease`) — remove `--raw` references, add `--json` where relevant\n\nThe goal: `export TOKEN=$(secrets lease github_token)` just works without any flags.",
      "priority": 2,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "cmd/secrets/lease.go"
      ]
    },
    {
      "id": "story-mlsr0ekt",
      "title": "Remove TTY detection and legacy output format flags — JSON always",
      "description": "Per cli-design standard: JSON is the only output format. No --human, no --output, no TTY auto-detection.\n\nChanges:\n1. `cmd/secrets/root.go`:\n   - Remove `--human` flag\n   - Remove `--output` flag\n   - Remove `output.HumanMode` and `output.OutputFormat` references\n2. `internal/output/formatter.go`:\n   - Remove TTY detection (`isTerminal`)\n   - `GetFormatter()` always returns `JSONFormatter`\n   - Remove `ValidateMode()` (no longer needed)\n   - Remove `OutputMode` type and constants (ModeJSON, ModeTable, ModeRaw)\n3. `internal/output/table.go` — delete this file entirely (no table output)\n4. `internal/output/raw.go` — keep for internal use by lease command but remove from formatter system\n5. `internal/output/output.go`:\n   - Remove `HumanMode` and `OutputFormat` global vars\n   - Simplify `Print()` to always use JSON\n   - Remove `printHuman()` and `printData()` functions\n6. `internal/output/formatter_test.go` — update tests if they exist\n\nThe Print() function should just JSON-encode to stdout. Simple.",
      "priority": 3,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "internal/output/formatter.go",
        "cmd/secrets/root.go"
      ]
    },
    {
      "id": "story-mlsr0q1z",
      "title": "Self-documenting root command with command tree",
      "description": "Per cli-design standard: running `secrets` with no args should return a JSON command tree so agents can discover everything in one call.\n\nChanges to `cmd/secrets/root.go`:\n1. Add a `Run` function to `rootCmd` that outputs the command tree as JSON\n2. The output should follow the standard envelope:\n```json\n{\n  \"ok\": true,\n  \"command\": \"secrets\",\n  \"result\": {\n    \"description\": \"Portable credential management for AI agents\",\n    \"version\": \"<version>\",\n    \"commands\": [\n      {\"name\": \"init\", \"description\": \"Initialize the secrets store\", \"usage\": \"secrets init\"},\n      {\"name\": \"add\", \"description\": \"Add a secret to the store\", \"usage\": \"secrets add <name> [--value <val>] [--rotate-via <cmd>]\"},\n      {\"name\": \"lease\", \"description\": \"Get a secret value (raw by default)\", \"usage\": \"secrets lease <name> [--ttl 1h] [--client-id agent-x] [--json]\"},\n      {\"name\": \"revoke\", \"description\": \"Revoke a lease or killswitch\", \"usage\": \"secrets revoke <lease-id> | --all\"},\n      {\"name\": \"status\", \"description\": \"Daemon status and active leases\", \"usage\": \"secrets status\"},\n      {\"name\": \"health\", \"description\": \"Health check\", \"usage\": \"secrets health\"},\n      {\"name\": \"audit\", \"description\": \"View audit log\", \"usage\": \"secrets audit [--tail N]\"},\n      {\"name\": \"scan\", \"description\": \"Scan for hardcoded secrets\", \"usage\": \"secrets scan [path]\"},\n      {\"name\": \"env\", \"description\": \"Generate .env from .secrets.json\", \"usage\": \"secrets env [--force]\"},\n      {\"name\": \"exec\", \"description\": \"Run command with secrets as env vars\", \"usage\": \"secrets exec -- <command>\"},\n      {\"name\": \"cleanup\", \"description\": \"Remove expired lease files\", \"usage\": \"secrets cleanup\"},\n      {\"name\": \"serve\", \"description\": \"Start the daemon\", \"usage\": \"secrets serve\"},\n      {\"name\": \"update\", \"description\": \"Update to latest version\", \"usage\": \"secrets update\"}\n    ]\n  },\n  \"next_actions\": [\n    {\"command\": \"secrets status\", \"description\": \"Check daemon status\"},\n    {\"command\": \"secrets health\", \"description\": \"Full health check\"},\n    {\"command\": \"secrets lease <name>\", \"description\": \"Get a secret value\"}\n  ]\n}\n```\n3. This replaces cobra's default help output when no subcommand is given\n4. Keep `--help` working for detailed cobra help if someone wants it",
      "priority": 4,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "cmd/secrets/root.go"
      ]
    },
    {
      "id": "story-mlsr0zv6",
      "title": "Add fix field to all error responses",
      "description": "Per cli-design standard: every error response must include a `fix` field with plain-language remediation.\n\nReview ALL commands in cmd/secrets/ and ensure every error path includes actionable fix text:\n\n1. **Daemon not running errors** (most commands): fix = \"Start the daemon: secrets serve &\"\n2. **Secret not found** (lease): fix = \"Check available secrets: secrets status\"\n3. **Secret already exists** (add): fix = \"Use a different name, or update the existing secret\"\n4. **Lease not found** (revoke): fix = \"Check active leases: secrets status\"\n5. **Empty value** (add): fix = \"Provide a value via --value, stdin pipe, or interactive prompt\"\n6. **Store not initialized** (any): fix = \"Initialize the store: secrets init\"\n7. **Permission errors**: fix = \"Check file permissions on ~/.agent-secrets/ or use --skip-permission-check\"\n8. **Socket timeout**: fix = \"Daemon may be overloaded. Check: secrets health\"\n\nUpdate the output.Error() and output.ErrorMsg() helpers to accept an optional fix string, or add a new ErrorWithFix() helper. Make sure the `fix` field appears in the JSON envelope.\n\nAlso update `internal/types/errors.go` UserError type to map to the new error envelope structure (it already has Suggestion field — make sure that becomes `fix` in the JSON output).",
      "priority": 5,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "internal/output/output.go",
        "cmd/secrets/lease.go"
      ]
    },
    {
      "id": "story-mlsr197b",
      "title": "Add list command to show all stored secret names",
      "description": "Agents need to know what secrets are available. Currently there's no `secrets list` command — you have to infer from `secrets status` which only shows a count.\n\nAdd a new `cmd/secrets/list.go`:\n1. New `listCmd` cobra command: `secrets list`\n2. Calls daemon RPC to get list of secret names (may need new daemon method, or use existing status method if it returns names)\n3. Returns JSON envelope:\n```json\n{\n  \"ok\": true,\n  \"command\": \"secrets list\",\n  \"result\": {\n    \"secrets\": [\n      {\"name\": \"github_token\", \"has_rotation\": true, \"active_leases\": 1},\n      {\"name\": \"anthropic_key\", \"has_rotation\": false, \"active_leases\": 0}\n    ],\n    \"count\": 2\n  },\n  \"next_actions\": [\n    {\"command\": \"secrets lease github_token\", \"description\": \"Lease github_token\"},\n    {\"command\": \"secrets lease anthropic_key\", \"description\": \"Lease anthropic_key\"},\n    {\"command\": \"secrets add <name>\", \"description\": \"Add a new secret\"}\n  ]\n}\n```\n4. The `next_actions` should include a lease command for EACH secret — this is the HATEOAS magic, agents can discover and use secrets in one flow\n5. Register in `cmd/secrets/root.go`\n6. If the daemon doesn't support listing secret names, add a new RPC method `secrets.list` in `internal/daemon/handlers.go` and `internal/daemon/protocol.go`\n\nThis is critical for agent discoverability.",
      "priority": 6,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "cmd/secrets/",
        "internal/daemon/"
      ]
    },
    {
      "id": "story-mlsr1icp",
      "title": "Update README, SKILL.md, and AGENTS.md for new CLI design",
      "description": "Update all documentation to reflect the new agent-first CLI design:\n\n1. **README.md** — Rewrite quick start and examples:\n   - Show `secrets lease name` returns raw value by default\n   - Show `export TOKEN=$(secrets lease github_token)` as the primary pattern\n   - Show JSON envelope examples with `--json`\n   - Show `secrets` (root) returns command tree\n   - Remove references to `--raw`, `--human`, `--output` flags\n   - Add `secrets list` to command reference\n\n2. **skills/secret-management/SKILL.md** — Update the agent skill doc:\n   - Emphasize: `secrets lease name` → raw value, no flags needed\n   - Show `secrets list` for discovery\n   - Show `secrets` root for command tree\n   - Update all examples\n   - Remove `--raw` references\n\n3. **AGENTS.md** — Update any agent-specific notes about output format",
      "priority": 7,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "README.md",
        "skills/secret-management/SKILL.md"
      ]
    },
    {
      "id": "story-mlsuuq2i",
      "title": "Add update and delete commands for secrets",
      "description": "Add two new commands to manage existing secrets:\n\n**`secrets update <name>`** — Replace the value of an existing secret.\n- Same input methods as `add`: --value flag, stdin pipe, or interactive prompt\n- Fails if secret doesn't exist (use `add` for new secrets)\n- Returns JSON envelope with next_actions\n- Add RPC method `secrets.update` in `internal/daemon/handlers.go` and `internal/daemon/protocol.go`\n- Handler: call `store.Add()` (which overwrites) but only if secret already exists — check first\n\n**`secrets delete <name>`** — Remove a secret from the store.\n- Requires the secret name as argument\n- Add `--force` flag to skip confirmation (for agent use, default behavior)\n- Revokes any active leases for this secret before deleting\n- Returns JSON envelope confirming deletion with next_actions\n- Add RPC method `secrets.delete` in `internal/daemon/handlers.go` and `internal/daemon/protocol.go`\n- Handler: revoke leases for this secret, then call `store.Remove()` or equivalent\n\nBoth commands:\n1. Create `cmd/secrets/update_secret.go` and `cmd/secrets/delete.go`\n2. Register in `cmd/secrets/root.go`\n3. Update the root command tree (the self-documenting JSON) to include both\n4. Include proper `fix` fields on errors\n5. Return contextual `next_actions`\n\nAlso add `secrets delete` alias `secrets rm` for convenience.",
      "priority": 1,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "cmd/secrets/root.go",
        "internal/daemon/handlers.go"
      ]
    },
    {
      "id": "story-mlsvicrr",
      "title": "Backwards compatibility: restore deprecated flags with warnings",
      "description": "Restore --raw, --human, --output as hidden deprecated flags that print STDERR warnings. Add success as alias for ok in JSON envelope for one version cycle.\n\n1. cmd/secrets/lease.go: Add --raw back as hidden flag. When used, print to STDERR: \"WARNING: --raw is deprecated and now the default. Remove from scripts. Will be removed in v0.6.0\". Still outputs raw (already default).\n\n2. cmd/secrets/root.go: Add --human and --output back as hidden flags. When used, print STDERR deprecation warnings. Both are no-ops.\n\n3. internal/output/output.go: Add Success bool json:\"success\" to Response that mirrors OK. Add DeprecationWarning(msg string) helper that prints to STDERR.\n\n4. README.md: Add migration guide section for v0.4.x → v0.5.x",
      "priority": 1,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "cmd/secrets/lease.go",
        "cmd/secrets/root.go",
        "internal/output/output.go"
      ]
    },
    {
      "id": "story-mlt0pwra",
      "title": "Remove MCP references, credit Alex Hillman, clean up README",
      "description": "Three changes to README.md and skills/secret-management/SKILL.md:\n\n1. **Remove MCP section** from README.md — delete the \"### MCP Server Integration\" section and its \"Coming soon\" text. We're not doing MCP.\n\n2. **Remove MCP section** from skills/secret-management/SKILL.md — delete the \"### MCP Server Integration\" section.\n\n3. **Credit Alex Hillman** in README.md — Add an \"Inspiration\" or \"Credit\" section near the bottom:\n```markdown\n## Inspiration\n\nThis project was inspired by [Alex Hillman's approach](https://x.com/alexhillman/status/2005334574973296911) to agent credential management — the insight that agents shouldn't be anywhere near ALL your passwords. Scoped, time-bounded, audited access with a killswitch.\n```\n\n4. Also update the \"Why?\" section to reference this philosophy more directly — agents need secrets but giving them raw access to your password manager is a terrible idea.",
      "priority": 1,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "README.md",
        "skills/secret-management/SKILL.md"
      ]
    },
    {
      "id": "story-mlt170vk",
      "title": "Test coverage: internal/output envelope and formatters",
      "description": "Boost test coverage for internal/output from 38.5% to 90%+.\n\nAdd/expand tests in `internal/output/output_test.go`:\n\n1. **Response envelope shape tests:**\n   - Success() returns correct {ok: true, command, result, next_actions} shape\n   - Error() returns correct {ok: false, error: {message, code}, fix, next_actions} shape\n   - ErrorWithFix() populates fix field\n   - Success field mirrors OK field (backwards compat)\n   - Command field is populated\n   - NextActions serialization\n\n2. **JSON formatter tests** (internal/output/json_test.go):\n   - Verify JSON output matches expected envelope\n   - Verify omitempty works (no null fields)\n   - Error responses include fix field\n\n3. **Action builder tests:**\n   - ActionLease, ActionAdd, ActionRevoke etc. return correct command strings\n   - ActionsAfterAdd, ActionsAfterLease return contextual actions\n   - ActionsWhenEmpty, ActionsWhenNotInitialized\n\n4. **Deprecation warning tests:**\n   - DeprecationWarning writes to STDERR not STDOUT\n   - Verify warning message format\n\n5. **Raw formatter tests** (internal/output/raw_test.go if not covered):\n   - Raw format outputs data values only\n   - Handles maps, slices, strings, nil",
      "priority": 1,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "internal/output/output_test.go"
      ]
    },
    {
      "id": "story-mlt171hg",
      "title": "Test coverage: daemon handlers (list, update, delete)",
      "description": "Add tests for the new daemon RPC handlers in `internal/daemon/handlers_test.go`:\n\n1. **List handler tests:**\n   - List with no secrets returns empty array\n   - List with secrets returns names, rotation status, lease counts\n   - List response includes contextual next_actions with lease commands per secret\n\n2. **Update handler tests (if update RPC exists):**\n   - Update existing secret succeeds\n   - Update non-existent secret fails with appropriate error\n   - Update preserves rotation config\n\n3. **Delete handler tests (if delete RPC exists):**\n   - Delete existing secret succeeds\n   - Delete non-existent secret fails\n   - Delete revokes active leases for that secret\n   - Delete response includes appropriate next_actions\n\n4. **Error response tests:**\n   - All handlers return proper error envelope with fix field\n   - Daemon connection errors suggest \"secrets serve &\"",
      "priority": 2,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "internal/daemon/handlers_test.go"
      ]
    },
    {
      "id": "story-mlt1721h",
      "title": "Test coverage: cmd/secrets command tests",
      "description": "Add tests for cobra command setup and argument validation in `cmd/secrets/root_test.go`:\n\n1. **Root command tests:**\n   - Running with no args outputs JSON command tree (verify ok, result.commands array)\n   - Verify all expected subcommands are registered\n\n2. **Lease command tests:**\n   - Default output is raw (no --json flag)\n   - --json flag produces JSON envelope\n   - --raw flag is accepted (deprecated no-op) \n   - --ttl and --client-id flags are parsed\n\n3. **Add command tests:**\n   - --value flag is parsed\n   - --rotate-via flag is parsed\n\n4. **Delete command tests:**\n   - Requires name argument\n   - --force flag is parsed\n   - Aliases include \"rm\"\n\n5. **Deprecated flag tests:**\n   - --human flag accepted without error\n   - --output flag accepted without error\n   - These are no-ops but shouldn't crash",
      "priority": 3,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "cmd/secrets/root_test.go"
      ]
    },
    {
      "id": "story-mlt172li",
      "title": "Test coverage: internal/update and internal/types",
      "description": "Boost coverage for the two lowest-coverage packages:\n\n1. **internal/update/** (14.5% → 70%+):\n   - Add tests in `internal/update/update_test.go`\n   - Test version comparison logic\n   - Test update check with mock HTTP (or skip network tests)\n   - Test background update check doesn't block\n\n2. **internal/types/** (0% → 80%+):\n   - Add `internal/types/types_test.go`\n   - Test ExitCodeFromError mapping\n   - Test UserError creation and field access\n   - Test NewUserError with context\n   - Test error code constants",
      "priority": 4,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "internal/update/update_test.go"
      ]
    },
    {
      "id": "story-mlt2jat9",
      "title": "Integration tests: full agent workflow with new commands",
      "description": "Expand integration_test.go with end-to-end tests that exercise the full agent workflow using the actual binary + daemon.\n\nAdd these integration test functions (all with //go:build integration tag):\n\n1. **TestAgentWorkflow** — The complete happy path an agent would follow:\n   - `secrets init` → verify JSON envelope {ok: true}\n   - Start daemon (`secrets serve` in background)\n   - `secrets` (root) → verify command tree JSON, all commands listed\n   - `secrets add test_key --value \"sk-test123\"` → verify success\n   - `secrets add another_key --value \"val2\"` → add second secret\n   - `secrets list` → verify both secrets appear with names\n   - `secrets lease test_key` → verify raw value output \"sk-test123\" (no JSON)\n   - `secrets lease test_key --json` → verify JSON envelope with value, lease_id, next_actions\n   - `secrets update test_key --value \"sk-updated\"` → verify success\n   - `secrets lease test_key` → verify returns \"sk-updated\"\n   - `secrets delete another_key --force` → verify deletion\n   - `secrets list` → verify only test_key remains\n   - `secrets revoke --all` → killswitch\n   - `secrets status` → verify no active leases\n   - Stop daemon\n\n2. **TestDeprecatedFlags** — Verify backwards compat:\n   - `secrets lease test_key --raw` → still works, returns value\n   - `secrets status --human` → doesn't crash\n   - `secrets status --output json` → doesn't crash\n   - Check STDERR for deprecation warnings\n\n3. **TestErrorResponses** — Verify error envelopes:\n   - `secrets lease nonexistent` → verify {ok: false, error: {message, code}, fix}\n   - `secrets delete nonexistent` → verify error with fix suggestion\n   - `secrets update nonexistent --value x` → verify error\n\n4. **TestJSONEnvelopeShape** — Strict envelope validation:\n   - Every command's JSON output has `ok`, `command`, `result` or `error`, `next_actions`\n   - `next_actions` items have `command` and `description` fields\n   - Error responses have `fix` field\n\nEach test should use a temp HOME dir and start/stop its own daemon instance. Use the existing helper functions (getBinaryPath, runCommand) from the file.",
      "priority": 1,
      "passes": true,
      "validationCommand": "cd /home/joel/Code/joelhooks/agent-secrets && go build ./cmd/secrets/ && go test ./...",
      "targetFiles": [
        "integration_test.go"
      ]
    }
  ],
  "metadata": {
    "createdAt": "2026-02-19T00:53:39.274Z",
    "totalIterations": 15,
    "lastIteration": "2026-02-19T06:24:30.605Z"
  }
}