{"_id":"@benvenker/philip","_rev":"6-530a0c0f002219ba74ab553598a4fa2c","name":"@benvenker/philip","dist-tags":{"latest":"0.1.5"},"versions":{"0.1.0":{"name":"@benvenker/philip","version":"0.1.0","keywords":["agent-skill","ai-documentation","documentation","cursor","claude","codex"],"author":"","license":"UNLICENSED","_id":"@benvenker/philip@0.1.0","maintainers":[{"name":"benvenker","email":"bvemails@gmail.com"}],"homepage":"https://github.com/benvenker/philip#readme","bugs":{"url":"https://github.com/benvenker/philip/issues"},"bin":{"philip":"bin/philip.js"},"dist":{"shasum":"e226574123774d3d35ed69e94d005016efe4012c","tarball":"https://registry.npmjs.org/@benvenker/philip/-/philip-0.1.0.tgz","fileCount":14,"integrity":"sha512-jfJDFlljIhosukMxcTlyXCGB0YQAFj53/ugTVImnCSXnLl1FQPioFpLTF59EW9X+HrCAJkwTxsmFy7SSzlJOlw==","signatures":[{"sig":"MEUCIQCgSSKFpPXXmdOM0hH2lXbPX8f5d3PDpVYpa4Szzy4L9QIgP9xnOugZUF5mlUxq9Ugd6A8JqxePZE+xeyfL9z5me+s=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":70237},"type":"commonjs","engines":{"node":">=18"},"gitHead":"f7eb50d9218c754789132683b43ec6ec4916457e","private":false,"scripts":{"check":"node bin/philip.js install --dry-run && npm pack --dry-run","pack:check":"npm pack --dry-run","install:skill":"node bin/philip.js install"},"_npmUser":{"name":"benvenker","email":"bvemails@gmail.com"},"repository":{"url":"git+https://github.com/benvenker/philip.git","type":"git"},"_npmVersion":"11.5.1","description":"Portable Agent Skill for writing, auditing, rewriting, and maintaining software documentation from code evidence.","directories":{},"_nodeVersion":"24.7.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/philip_0.1.0_1777847457188_0.5818386927898442","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@benvenker/philip","version":"0.1.1","keywords":["agent-skill","ai-documentation","documentation","cursor","claude","codex"],"author":"","license":"UNLICENSED","_id":"@benvenker/philip@0.1.1","maintainers":[{"name":"benvenker","email":"bvemails@gmail.com"}],"homepage":"https://github.com/benvenker/philip#readme","bugs":{"url":"https://github.com/benvenker/philip/issues"},"bin":{"philip":"bin/philip.js"},"dist":{"shasum":"087f6384a34ec26b69b5ccb8bf968bb711e2790b","tarball":"https://registry.npmjs.org/@benvenker/philip/-/philip-0.1.1.tgz","fileCount":14,"integrity":"sha512-bh6c1q8HGq32+ud0vaMH3x/HugEy+VNbqrWeIlsQS9nToRYm044uSgFYadY1ZmvSgA+TZ/2nTZyql+j6t5+Bpw==","signatures":[{"sig":"MEYCIQDbFFz3FSIkxYJpPpgnoQG2//G/HbPrLFJCon2Uz9hl2AIhAMdRPyY+We/madFxWs01Sf40ksto9kMd+4eeQtdegW9o","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@benvenker%2fphilip@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":70237},"type":"commonjs","engines":{"node":">=18"},"gitHead":"18f33d0ce011065f0c646d434fc8a1aac672e43c","private":false,"scripts":{"check":"node bin/philip.js install --dry-run && npm pack --dry-run","pack:check":"npm pack --dry-run","install:skill":"node bin/philip.js install"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:261cc53f-a358-486e-9419-cf0f67a5c324"}},"repository":{"url":"git+https://github.com/benvenker/philip.git","type":"git"},"_npmVersion":"11.13.0","description":"Portable Agent Skill for writing, auditing, rewriting, and maintaining software documentation from code evidence.","directories":{},"_nodeVersion":"24.14.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/philip_0.1.1_1777847578897_0.5830728270683139","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@benvenker/philip","version":"0.1.2","keywords":["agent-skill","ai-documentation","documentation","cursor","claude","codex"],"author":"","license":"UNLICENSED","_id":"@benvenker/philip@0.1.2","maintainers":[{"name":"benvenker","email":"bvemails@gmail.com"}],"homepage":"https://github.com/benvenker/philip#readme","bugs":{"url":"https://github.com/benvenker/philip/issues"},"bin":{"philip":"bin/philip.js"},"dist":{"shasum":"6724dbf4c2e8a63083d4070bae474ba3926b0533","tarball":"https://registry.npmjs.org/@benvenker/philip/-/philip-0.1.2.tgz","fileCount":15,"integrity":"sha512-8gxEXwW2BW60yWhfPTSfnH2zZFaBO9v4/woB7qMaJd8A5wqg5+8Nmy4NwPn+TUctH8vU5Ju6ztzXj3oUgeXMkQ==","signatures":[{"sig":"MEUCIQDmw5Qd1QMwcJngfd63iM3hztseodL7QqjkmFK0nRIx8QIgQ8JP+DsH7ILTZyL9s/KRUrTe/1nS5NRqEZqK6TO1Ayo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@benvenker%2fphilip@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":72886},"type":"commonjs","engines":{"node":">=18"},"gitHead":"22f705eb43a8cd8fdd6f836c1f2651710419beb8","private":false,"scripts":{"check":"node bin/philip.js install --dry-run && npm pack --dry-run","pack:check":"npm pack --dry-run","postinstall":"node scripts/postinstall.js","install:skill":"node bin/philip.js install"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:261cc53f-a358-486e-9419-cf0f67a5c324"}},"repository":{"url":"git+https://github.com/benvenker/philip.git","type":"git"},"_npmVersion":"11.13.0","description":"Portable Agent Skill for writing, auditing, rewriting, and maintaining software documentation from code evidence.","directories":{},"_nodeVersion":"24.14.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/philip_0.1.2_1777848452863_0.9908400068687053","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@benvenker/philip","version":"0.1.3","keywords":["agent-skill","ai-documentation","documentation","cursor","claude","codex"],"author":"","license":"UNLICENSED","_id":"@benvenker/philip@0.1.3","maintainers":[{"name":"benvenker","email":"bvemails@gmail.com"}],"homepage":"https://github.com/benvenker/philip#readme","bugs":{"url":"https://github.com/benvenker/philip/issues"},"bin":{"philip":"bin/philip.js"},"dist":{"shasum":"a6d96172a45e777d7383b91c23684106434b2b9b","tarball":"https://registry.npmjs.org/@benvenker/philip/-/philip-0.1.3.tgz","fileCount":15,"integrity":"sha512-wxx/0RHYZLLA4Qk/VKie6aarmByqQ77O9YY4kjDyW+HptJOmdzoUM7HOvirqes+X3l6GIyDZlE50TALKO2G20Q==","signatures":[{"sig":"MEYCIQDBcOn9NFjSuHkVF+Xr2wKqV2Iaf1BpyrpRuPYMmgeznQIhAO2W4vrM0K5CpqYBtJFD33ljtjkVu9hanqYHGjpTCBFG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@benvenker%2fphilip@0.1.3","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":73397},"type":"commonjs","engines":{"node":">=18"},"gitHead":"9ae0221de625e6c147810673ddbee14c8930618c","private":false,"scripts":{"check":"node bin/philip.js install --dry-run && npm pack --dry-run","pack:check":"npm pack --dry-run","postinstall":"node scripts/postinstall.js","install:skill":"node bin/philip.js install"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:261cc53f-a358-486e-9419-cf0f67a5c324"}},"repository":{"url":"git+https://github.com/benvenker/philip.git","type":"git"},"_npmVersion":"11.13.0","description":"Portable Agent Skill for writing, auditing, rewriting, and maintaining software documentation from code evidence.","directories":{},"_nodeVersion":"24.14.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/philip_0.1.3_1777848893034_0.6249375909436508","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@benvenker/philip","version":"0.1.4","keywords":["agent-skill","ai-documentation","documentation","cursor","claude","codex"],"author":"","license":"UNLICENSED","_id":"@benvenker/philip@0.1.4","maintainers":[{"name":"benvenker","email":"bvemails@gmail.com"}],"homepage":"https://github.com/benvenker/philip#readme","bugs":{"url":"https://github.com/benvenker/philip/issues"},"bin":{"philip":"bin/philip.js"},"dist":{"shasum":"907374fb9c79cc1311f70460793a9c0b52515fe9","tarball":"https://registry.npmjs.org/@benvenker/philip/-/philip-0.1.4.tgz","fileCount":26,"integrity":"sha512-tGDJiBqfa9A3dXPVfid60X2fApOcBd9fBfEwBzCYH7IhoqrbRsHMHL/WOhGfWoAYG/uA0MiysMctj6lEX1FRtw==","signatures":[{"sig":"MEYCIQDULeff0x6mxwrgg4YOhZTDJA4Cn2ru9j/pQmdBUk5njAIhAKk5idEVM3Ch4SC9BYVKCw7uVkgvKsN4KzQOyJnGpp+1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@benvenker%2fphilip@0.1.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":212272},"type":"commonjs","engines":{"node":">=18"},"gitHead":"75d0f00c7b3b08f8d1e3d472ef23c70a1c23da02","private":false,"scripts":{"check":"npm run test:lint-audit && npm run test:diff && npm run test:cli && node bin/philip.js install --dry-run && npm pack --dry-run","prepare":"husky","test:cli":"node --test scripts/test-philip-cli.mjs","test:diff":"node scripts/test-collect-philip-diff.mjs","pack:check":"npm pack --dry-run","postinstall":"node scripts/postinstall.js","install:skill":"node bin/philip.js install","test:lint-audit":"node scripts/test-audit-report-lint.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:261cc53f-a358-486e-9419-cf0f67a5c324"}},"repository":{"url":"git+https://github.com/benvenker/philip.git","type":"git"},"_npmVersion":"11.14.1","description":"Portable Agent Skill for writing, auditing, rewriting, and maintaining software documentation from code evidence.","directories":{},"_nodeVersion":"24.14.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"husky":"^9.1.7"},"_npmOperationalInternal":{"tmp":"tmp/philip_0.1.4_1778547845954_0.29125946768463806","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@benvenker/philip","version":"0.1.5","description":"Portable Agent Skill for writing, auditing, rewriting, and maintaining software documentation from code evidence.","type":"commonjs","repository":{"type":"git","url":"git+https://github.com/benvenker/philip.git"},"publishConfig":{"access":"public"},"bin":{"philip":"bin/philip.js"},"scripts":{"check":"npm run test:lint-audit && npm run test:diff && npm run test:cli && node bin/philip.js install --dry-run && npm pack --dry-run","test:lint-audit":"node scripts/test-audit-report-lint.mjs","test:diff":"node scripts/test-collect-philip-diff.mjs","test:cli":"node --test scripts/test-philip-cli.mjs","pack:check":"npm pack --dry-run","install:skill":"node bin/philip.js install","postinstall":"node scripts/postinstall.js","prepare":"husky"},"keywords":["agent-skill","ai-documentation","documentation","cursor","claude","codex"],"author":"","license":"UNLICENSED","private":false,"engines":{"node":">=18"},"devDependencies":{"husky":"^9.1.7"},"gitHead":"625846a579ea18ffb8bf1b0e80ff7c951900e486","_id":"@benvenker/philip@0.1.5","bugs":{"url":"https://github.com/benvenker/philip/issues"},"homepage":"https://github.com/benvenker/philip#readme","_nodeVersion":"24.14.1","_npmVersion":"11.14.1","dist":{"integrity":"sha512-LunV8F2Tx5W+kpwPJuOwXvAM3He5bxNtH+g2z3+bu2gFvtrbAlgMzF1eyQ7/bn2jWszegS/gYAjsp6MZ1ZhgZg==","shasum":"3525325f66f0df2baac88e604710a728b2720490","tarball":"https://registry.npmjs.org/@benvenker/philip/-/philip-0.1.5.tgz","fileCount":26,"unpackedSize":217612,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@benvenker%2fphilip@0.1.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDjMXdMDlrt3PP3dzmbyykLH5fI83sgSRtlPpdL8G6IGQIhAJ6wMVaiWNmlSoRgxo6aZX72ipR4HaW658j0PkjXJ+Cx"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:261cc53f-a358-486e-9419-cf0f67a5c324"}},"directories":{},"maintainers":[{"name":"benvenker","email":"bvemails@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/philip_0.1.5_1778552024340_0.5373710509274077"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T22:30:56.805Z","modified":"2026-05-12T02:13:45.190Z","0.1.0":"2026-05-03T22:30:57.341Z","0.1.1":"2026-05-03T22:32:59.051Z","0.1.2":"2026-05-03T22:47:33.037Z","0.1.3":"2026-05-03T22:54:53.181Z","0.1.4":"2026-05-12T01:04:06.138Z","0.1.5":"2026-05-12T02:13:44.850Z"},"bugs":{"url":"https://github.com/benvenker/philip/issues"},"license":"UNLICENSED","homepage":"https://github.com/benvenker/philip#readme","keywords":["agent-skill","ai-documentation","documentation","cursor","claude","codex"],"repository":{"type":"git","url":"git+https://github.com/benvenker/philip.git"},"description":"Portable Agent Skill for writing, auditing, rewriting, and maintaining software documentation from code evidence.","maintainers":[{"name":"benvenker","email":"bvemails@gmail.com"}],"readme":"# Philip\n\nPhilip is an AI documentation-writing skill for software projects. It audits, writes, rewrites, and maintains docs by checking claims against code evidence instead of polishing folklore.\n\n## What Philip Does\n\nPhilip supports four modes:\n\n| Mode | Use When | Output |\n| --- | --- | --- |\n| `audit` | \"What's wrong with our docs?\" | Severity-ranked documentation health report. |\n| `write` | \"Write docs for X.\" | New README, guide, API doc, runbook, or reference material. |\n| `rewrite` | \"Fix these stale docs.\" | Updated existing docs that match current code. |\n| `maintain` | \"Update docs for this PR.\" | Surgical doc patches for the current diff. |\n\nCore rule: every claim in generated docs must trace to local evidence: source code, tests, config, git history, or command output. If GitLab Orbit is available, Philip can use it as additional evidence, but Orbit is never required.\n\n## Install\n\nInstall Philip by placing the full directory in a skill location. Do not copy\nonly `SKILL.md`; Philip uses the root reference files and `Workflows/`.\n\n### Recommended: skills CLI\n\nUse the open Agent Skills installer:\n\n```bash\nnpx skills@latest add benvenker/philip\n```\n\nThis is the best path for most users. It finds the `philip` skill from this\nrepo and guides the user through the target agent and install method.\n\nFor a global install:\n\n```bash\nnpx skills@latest add benvenker/philip -g\n```\n\nFor a specific agent:\n\n```bash\nnpx skills@latest add benvenker/philip -a cursor\nnpx skills@latest add benvenker/philip -a codex\nnpx skills@latest add benvenker/philip -a claude-code\n```\n\nFor a non-interactive global install to one agent:\n\n```bash\nnpx skills@latest add benvenker/philip -g -a cursor -y\n```\n\nTo confirm Philip is discoverable before installing:\n\n```bash\nnpx skills@latest add benvenker/philip --list\n```\n\n### Direct npm package\n\nInstall the helper CLI, then copy Philip into a skill location:\n\n```bash\nnpm install -g @benvenker/philip\nphilip install\n```\n\nThe npm install prints the `philip install` next step so users are not left\nguessing. It does not silently write into `~/.agents/skills` during package\ninstall.\n\nFor a project-local install:\n\n```bash\nnpx @benvenker/philip install --project\n```\n\nThe installer writes the portable skill directory to `~/.agents/skills/philip`\nby default. It also supports `--target ~/.claude/skills`, `--target ~/.cursor/skills`,\n`--force`, and `--dry-run`.\n\nFor an explicit one-command global install:\n\n```bash\nPHILIP_AUTO_INSTALL=1 npm install -g @benvenker/philip\n```\n\n### Manual install\n\nRecommended shared locations:\n\n```bash\n# User-level, shared by Agent Skills clients that support the common path\nmkdir -p ~/.agents/skills\ncp -R philip ~/.agents/skills/philip\n\n# Project-level, shared with a repository\nmkdir -p .agents/skills\ncp -R philip .agents/skills/philip\n```\n\nAgent-specific fallbacks:\n\n```bash\n# Claude Code fallback\nmkdir -p ~/.claude/skills\ncp -R philip ~/.claude/skills/philip\n\n# Cursor fallback\nmkdir -p ~/.cursor/skills\ncp -R philip ~/.cursor/skills/philip\n\n# GitHub Copilot project fallback\nmkdir -p .github/skills\ncp -R philip .github/skills/philip\n```\n\nFor broader reuse beyond one machine or one repo, package Philip as a plugin\nfor the target agent ecosystem. Keep the portable skill directory usable on its\nown; plugin metadata should not become required for normal use.\n\n## Publishing\n\nThis repo can publish the portable skill as `@benvenker/philip` on npm. The\npackage includes the skill files, the explicit `philip` installer CLI, and a\n`postinstall` notice that tells npm users to run `philip install`. It does not\nwrite into user skill folders during npm install unless `PHILIP_AUTO_INSTALL=1`\nis set.\n\nPublishing is tag-driven through GitHub Actions and npm trusted publishing.\nThere is no npm token in this repo.\n\nFirst-time npm setup is different from later releases because npm requires a\npackage to exist before trusted publishing can be configured. `@benvenker/philip`\nhas already been bootstrapped; use this section only if the package is deleted,\nrenamed, or moved to a new scope.\n\nBootstrap the package once, then configure trusted publishing:\n\n```bash\nnpm publish --access public\n```\n\nThen on npmjs.com, add a trusted publisher for `@benvenker/philip` using GitHub\nActions, repository `benvenker/philip`, and workflow `.github/workflows/publish.yml`.\n\nAfter that, future releases are tag-driven and tokenless.\n\nBefore cutting a release:\n\n```bash\nnpm run check\nnpm pack --dry-run\n```\n\nTo publish a release:\n\n```bash\nnpm version patch   # or minor / major\ngit push origin main --follow-tags\n```\n\nThe pushed `vX.Y.Z` tag checks that the tag matches `package.json`, publishes\nthat version to npm, and creates the GitHub Release marked as latest.\n\nAfter publishing, smoke-test the public package from a temporary directory:\n\n```bash\nnpx @benvenker/philip install --dry-run\n```\n\nExpected structure:\n\n```text\nphilip/\n  SKILL.md\n  Audit.md\n  Writing.md\n  DocTypes.md\n  Exploration.md\n  OrbitIntegration.md\n  Validation.md\n  Workflows/\n    Audit.md\n    Write.md\n    Rewrite.md\n    Maintain.md\n  fixtures/\n    audit-lint/\n  scripts/\n    audit-report-lint.mjs\n  README.md\n```\n\n## Usage\n\nAsk for the mode naturally:\n\n```text\nUse Philip to audit the docs for this repo.\n```\n\n```text\nUse Philip to write a setup guide for the local development workflow.\n```\n\n```text\nUse Philip to rewrite docs/api.md so it matches the current route handlers.\n```\n\n```text\nUse Philip to update docs for the current PR diff.\n```\n\nPhilip starts by routing through `SKILL.md`, then loads only the needed workflow and reference files. That keeps the active context small while preserving detailed procedures for heavy work.\n\n### Diff Data Layer\n\nUse `philip diff` when a branch needs a bounded evidence packet for review, documentation maintenance, or agent handoff:\n\n```bash\nphilip diff\nphilip diff --json\n```\n\nOn success, Philip writes an **Actionable diff** JSON file and prints its repo-relative path:\n\n```text\nWrote Philip diff data to .philip/artifacts/{workstream}/philip-diff.json\n```\n\nUse `--json` when another tool or agent needs to parse the result envelope from stdout:\n\n```json\n{\n  \"ok\": true,\n  \"artifact\": {\n    \"kind\": \"actionable_diff\",\n    \"path\": \".philip/artifacts/{workstream}/philip-diff.json\",\n    \"schemaVersion\": 1\n  },\n  \"comparison\": {},\n  \"metrics\": {}\n}\n```\n\nThe **Artifact store** is `.philip/artifacts/`. It is generated local output. Users may add it to `.gitignore` if that matches their repo policy, but Philip does not silently edit `.gitignore`.\n\nWorkstream names are deterministic:\n\n- Current branch names are sanitized, so `feature/html-artifacts` becomes `feature-html-artifacts`.\n- Detached HEAD uses `detached-{shortSha}`.\n- Non-Git directories or Git repos without a usable commit use `current`.\n\n`philip-diff.json` is factual input for downstream agents, not a rendered report. The **Diff collector script** records the implemented data contract:\n\n- `repo`, `comparison`, and `provenance` with Git command provenance but no raw command output.\n- `changedFiles`, including tracked, untracked, deleted, renamed, additions/deletions where Git provides them, and mechanical surface flags.\n- **Diff impact metrics**, **Repo inventory**, and `changedSurfaces` as factual counts and groupings.\n- `changedIdentifiers` from changed lines or bounded untracked-file reads.\n- `localArtifacts` metadata for plans, investigations, reports, design notes, docs, and HTML files.\n- `verification` metadata listing discovered validation commands and changed tests; `philip diff` does not run those commands.\n\nV1 non-goals are explicit: no HTML mode, no deterministic HTML renderer, no automatic Markdown branch report, no full diff hunks, no severity/confidence/risk/importance scoring, no occurrence scan, and no silent `.gitignore` edits.\n\nExample downstream prompt for a Markdown PR brief:\n\n```text\nRead .philip/artifacts/{workstream}/philip-diff.json as bounded evidence.\nWrite a Markdown PR brief that cites changed file paths, verification commands discovered, and any local artifacts referenced in the JSON.\nDo not invent severity, risk, confidence, or importance. For claims beyond the JSON, inspect the referenced files or Git commands and cite what you checked.\n```\n\nExample downstream prompt for an HTML review artifact:\n\n```text\nUse .philip/artifacts/{workstream}/philip-diff.json to create a self-contained HTML artifact for branch review.\nTreat the JSON as evidence, not a design mandate. Show changed files, Diff impact metrics, Repo inventory highlights, verification metadata, and local artifacts.\nDo not claim Philip generated this HTML automatically, and do not add facts that are not in the JSON unless you inspect and cite the referenced paths or commands.\n```\n\nExample downstream prompt for agent handoff:\n\n```text\nUse .philip/artifacts/{workstream}/philip-diff.json to prepare a handoff prompt for the next agent.\nSummarize the Actionable diff, list the highest-leverage files to inspect, include discovered but not-run verification commands, and state which claims are bounded to the JSON.\nFor anything beyond the JSON, tell the next agent exactly which paths or Git commands to inspect first.\n```\n\n### Audit Report Linter\n\nPhilip includes a dependency-free structure linter for audit reports:\n\n```bash\nphilip lint-audit path/to/audit.md\nphilip lint-audit path/to/plan.md --format plan\nphilip lint-audit - --json\n```\n\n`Confidence` fields must start with `High`, `Medium`, or `Low`. Invalid\nconfidence labels are structural lint errors.\n\n### Agent CLI Contract\n\nPhilip exposes its machine-readable contract and an agent quick guide in-tool:\n\n```bash\nphilip --robot-triage\nphilip capabilities --json\nphilip robot-docs guide\nphilip help diff\n```\n\nUse `philip --robot-triage` when an agent needs a one-call status packet. It\nprints exactly one JSON object to stdout and does not write artifacts. The\nobject includes the CLI contract version, structured surfaces, `.philip/artifacts/`\nhealth, current and latest `philip-diff.json` paths when present, discovered\nverification commands, recommended next commands, recovery hints, and exit\ncodes.\n\nUser-input errors exit 2 and write diagnostics to stderr. Requested JSON goes to\nstdout without progress text.\n\nInstalled-skill contexts can invoke the script directly when the `philip` CLI is\nnot on `PATH`:\n\n```bash\nnode ~/.agents/skills/philip/scripts/audit-report-lint.mjs path/to/audit.md\nnode scripts/audit-report-lint.mjs --format audit -\n```\n\nThe linter checks structure only: required sections, finding fields,\nverification labels, coverage/scope disclosure, Orbit disclosure, and plan\nordering. It does not verify whether cited code evidence is factually true.\n\n## Modes\n\n### Audit\n\nPhilip inventories documentation, explores the codebase, cross-references claims, and produces a severity-ranked report.\n\nAudit checks include:\n\n- Missing setup, API, architecture, operations, security, and troubleshooting docs.\n- Commands that no longer exist.\n- Environment variables not documented.\n- API examples that diverge from handlers, schemas, or tests.\n- Recent code changes that did not update docs.\n- Undocumented public symbols and high-churn areas.\n- Doc-local completeness gaps where a design, architecture, setup, README, or product-contract doc names a public surface but never explains it or delegates it to another doc.\n\n### Write\n\nPhilip deep-reads the source, chooses the right doc type, drafts from evidence, removes AI filler, and verifies examples where safe.\n\nSupported doc types include README, setup guide, how-to guide, API reference, architecture guide, runbook, troubleshooting guide, changelog, contributor guide, security guide, migration guide, and glossary.\n\nFor design, architecture, README, setup, and product-contract docs, Philip also runs a doc-local consistency pass: every named binary, command, tool, env var, config file, hook, package script, package artifact, or shipped doc must be explained in that doc or explicitly delegated to the owning doc.\n\n### Rewrite\n\nPhilip updates existing docs without flattening useful structure. It uses git history to identify renamed commands, deleted paths, changed config, stale examples, and public surfaces that the rewritten doc names but fails to close locally.\n\nDefault behavior: keep the good parts, remove the trapdoors.\n\n### Maintain\n\nPhilip reads the current diff, classifies user-visible changes, finds affected docs, and patches only the sections that need to change.\n\nThis is the mode for PRs and merge requests.\n\n## Validation\n\nUse `Validation.md` before publishing changes to Philip itself. It covers skill\nstructure, portability, forward-test prompts, and output checks.\n\n## Optional GitLab Orbit Context\n\nPhilip does not set up, configure, or require GitLab Orbit. If the user's\nproject already has Orbit available in their agent environment, Philip can use\nit as an additional read-only context source. Otherwise, Philip uses local\nfilesystem search, `rg`, and git history.\n\nWhen already available, Orbit can help with:\n\n- File ownership.\n- Cross-file dependencies through `File`, `Definition`, and `ImportedSymbol` nodes.\n- Merge request history.\n- Undocumented hotspots.\n- Security context.\n- Graph paths between docs and code.\n\nDo not ask users to create GitLab tokens or enable Orbit as part of using this skill.\n\n## Writing Standards\n\nPhilip bans common AI tells: overused em dash constructions, \"It's not X it's Y\", \"Here's why\", \"Let's dive in\", \"At its core...\", \"It's worth noting...\", marketing adjectives, copula padding like \"serves as\", vague attribution, forced triples, and generic chatbot conclusions.\n\nThe writing style is practical:\n\n- Start with the task.\n- Put prerequisites before commands.\n- Include verification steps.\n- Mark unverified examples.\n- Cite code evidence.\n- Delete stale claims instead of burying them.\n\n## Quality Bar\n\nPhilip is done only when:\n\n- Requested docs are written or the audit report is complete.\n- Commands, env vars, paths, APIs, and examples trace to evidence.\n- Unsupported claims are removed or marked unknown.\n- The final answer states what changed, what was checked, and what remains risky.\n\nIf a setup guide has three commands and two are stale, Philip says so. Then he fixes it.\n","readmeFilename":"README.md"}