Skip to content

Commit d1f1bf8

Browse files
88plugclaude
88plug
and
claude
committed
docs: add MkDocs Material site + GitHub Pages workflow
Add a full-width Material for MkDocs documentation site built from the README, with a GitHub Pages deploy workflow. docs/index.md is a copy of the README so the site has a landing page; mkdocs.yml uses the Material theme with light/dark toggle, search, and code-copy. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 8459b08 commit d1f1bf8

3 files changed

Lines changed: 274 additions & 0 deletions

File tree

‎.github/workflows/pages.yml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# .github/workflows/pages.yml
2+
# Builds the MkDocs site and deploys it to GitHub Pages on every docs change.
3+
# NOTE: the repo's Pages site must be enabled ONCE out-of-band (the Actions token
4+
# cannot create it):
5+
# gh api -X POST repos/OWNER/REPO/pages -f build_type=workflow
6+
name: Pages
7+
8+
on:
9+
workflow_dispatch:
10+
push:
11+
branches:
12+
- main
13+
paths:
14+
- "README.md"
15+
- "docs/**"
16+
- "mkdocs.yml"
17+
- ".github/workflows/pages.yml"
18+
19+
permissions:
20+
contents: read
21+
pages: write
22+
id-token: write
23+
24+
concurrency:
25+
group: pages
26+
cancel-in-progress: true
27+
28+
jobs:
29+
build:
30+
runs-on: ubuntu-latest
31+
steps:
32+
- name: Check out repository
33+
uses: actions/checkout@v4
34+
35+
- name: Install Python
36+
uses: actions/setup-python@v5
37+
with:
38+
python-version: "3.13"
39+
40+
- name: Configure Pages
41+
uses: actions/configure-pages@v5
42+
with:
43+
enablement: true # no-op once the site exists; see header note
44+
45+
- name: Build site
46+
shell: bash
47+
run: |
48+
set -euo pipefail
49+
python -m pip install --upgrade pip mkdocs mkdocs-material
50+
mkdocs build --site-dir site
51+
52+
- name: Upload Pages artifact
53+
uses: actions/upload-pages-artifact@v3
54+
with:
55+
path: site
56+
57+
deploy:
58+
needs: build
59+
runs-on: ubuntu-latest
60+
environment:
61+
name: github-pages
62+
url: ${{ steps.deployment.outputs.page_url }}
63+
steps:
64+
- name: Deploy to GitHub Pages
65+
id: deployment
66+
uses: actions/deploy-pages@v4

‎docs/index.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
<div align="center">
2+
3+
# Project Prospector
4+
5+
A Claude Code plugin that catalogs and ranks everything you've built or sketched on a machine — half-finished repos, one-off scripts, dormant ideas, running services — into a tiered ranking by idea-novelty and leverage.
6+
7+
[![plugin-validate](https://github.com/88plug/project-prospector/actions/workflows/plugin-validate.yml/badge.svg)](https://github.com/88plug/project-prospector/actions/workflows/plugin-validate.yml)
8+
[![License: FSL-1.1-ALv2](https://img.shields.io/badge/license-FSL--1.1--ALv2-blue?style=flat)](LICENSE.md)
9+
[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-8A2BE2?style=flat)](https://github.com/88plug/claude-code-plugins)
10+
11+
</div>
12+
13+
## Install
14+
15+
```text
16+
/plugin marketplace add 88plug/project-prospector
17+
/plugin install project-prospector@project-prospector
18+
```
19+
20+
## Quickstart
21+
22+
Ask in plain language — no command to memorize:
23+
24+
```text
25+
What have I built on this laptop? Rank my projects by which ideas are most original.
26+
```
27+
28+
You get a tiered ranking, strongest idea first, with `[idea]/[LIVE]/[dormant]`
29+
tags and an evidence-anchored one-liner for each entry:
30+
31+
```text
32+
Tier S — genius
33+
benchie [LIVE] — predicts engine latency without launching it
34+
(perfmodel/roofline.py), 72 commits this week.
35+
36+
Tier A — elegant, high-leverage
37+
searxng-mcp — token-efficient self-hosted search for agents; dual-IP failover.
38+
39+
Dormant
40+
old-scraper — last real commit pre-cutoff; cosmetic touch since.
41+
```
42+
43+
## What it does
44+
45+
Project Prospector surveys a whole machine for *your own* work and ranks it by
46+
the quality of the idea, not how finished it is. A half-built concept with a
47+
novel core can outrank a polished CRUD app. The name is the intent: you're
48+
prospecting a messy filesystem for the few strong ideas buried in it.
49+
50+
It runs a two-pass, parallel, read-only sweep, then synthesizes one ranking:
51+
52+
- **Catalog pass** — clusters the filesystem into themed groups (crypto,
53+
homelab, AI-tooling, not alphabetical) and gives each cluster its own
54+
read-only explorer agent that reads READMEs, runs `git log` since the cutoff,
55+
and judges non-git dirs by file mtimes.
56+
- **Blind-spot pass** — a second wave of agents that each attack one place a
57+
file sweep structurally misses, so you don't confidently report "that's
58+
everything" and be wrong.
59+
- **Synthesize** — de-duplicates, separates idea quality from execution state,
60+
and produces an S–D tiered ranking with evidence-anchored rationale and
61+
alternative lenses.
62+
63+
## Why two passes
64+
65+
One agent reading directories top to bottom misses most of the value. The strong
66+
ideas hide in places a plain `ls` never reaches, so the blind-spot pass covers:
67+
68+
- **Transcripts** — `~/.claude/projects/` slugs, grepped for idea and plan
69+
language. Finds ideas discussed but never turned into a folder.
70+
- **Other agent CLIs** — `~/.codex/`, `~/.opencode/`, `~/.config/` agent tools.
71+
Finds work done through other tools.
72+
- **Running services and history** — shell history themes, `crontab -l`,
73+
`systemctl --user` timers and units, `docker ps -a`, long-running processes.
74+
Reveals what is actually live versus abandoned.
75+
- **Research artifacts** — substantive docs in `~/Downloads`, `~/Documents`,
76+
`~/Desktop`, and browser bookmarks and history. Finds ideas you're circling
77+
but haven't built.
78+
- **Beyond home** — `/opt`, `/srv`, `/mnt`, `/media`, nested repos inside other
79+
projects, and system-wide recently-modified source. Confirms nothing hides
80+
outside the obvious tree.
81+
82+
## How it ranks
83+
84+
The default axis is idea-novelty, non-obvious insight, and leverage — not lines
85+
of code, not polish. Output is structured as tiers, strongest first:
86+
87+
- Tier S — genius: genuinely novel core insight, high ceiling.
88+
- Tier A — elegant, high-leverage: strong idea, clear payoff.
89+
- Tier B — clever hacks, narrower: smart but bounded in scope.
90+
- Tier C — solid, low novelty: useful and reliable, not inventive.
91+
- Tier D — utility, scratch, and stubs, plus a Dormant list.
92+
93+
Each entry carries a tag that separates the idea from its execution state:
94+
`[idea]` (no codebase yet, can still rank at the top), `[LIVE]` (currently
95+
running), and `[dormant]` (untouched before the cutoff). Every cited path,
96+
commit count, or number is verified against disk before it goes in the report.
97+
98+
<details>
99+
<summary>Alternative lenses (ask for any of these instead)</summary>
100+
101+
- **Initiative clustering** — group projects into real themes and rank the
102+
clusters by coherence.
103+
- **Momentum** — accelerating versus stalled, by the trend of commits over time.
104+
- **Kill list** — what to archive or delete as dead weight, with the reason.
105+
- **Authorship / provenance** — an honest share of what you wrote versus
106+
vendored, forked, or scaffolded.
107+
- **Loss-risk / bus-factor** — valuable work in danger of vanishing (zero
108+
commits, unpushed branches, scratch dirs, no backup).
109+
110+
</details>
111+
112+
## Usage and arguments
113+
114+
Two inputs shape every run, both stated in plain language:
115+
116+
- **Time window** — relative dates resolve to an absolute cutoff (e.g. "last 3
117+
months"). Defaults to roughly 3 months if unspecified, and says so.
118+
Recency is judged by substantive activity (real commits, content of changes),
119+
not raw mtimes bumped by a generated file or a formatting-only commit.
120+
- **Scope and exclusions** — narrow the scope to a theme ("just my homelab
121+
projects"), a directory, or a non-home root, and exclude paths to skip
122+
("ignore my work repo"). The exclusion is honored verbatim by every agent.
123+
124+
Examples:
125+
126+
```text
127+
Take stock of my half-finished repos from this week.
128+
Catalog my side projects, but ignore my day-job monorepo.
129+
What's the single most original thing I've built since I started benchie?
130+
Audit /srv on this server and give me the kill list.
131+
```
132+
133+
The written deliverable scales to the ask: a top-3 question gets a short
134+
shortlist, "catalog everything" gets the full S–D census with the dormant tail.
135+
136+
> [!NOTE]
137+
> Project Prospector is strictly read-only. It inspects; it never edits, moves,
138+
> deletes, commits, or starts and stops services. Everything read off disk is
139+
> treated as untrusted data, not instructions (prompt-injection hardened). If a
140+
> finding warrants action, that's a separate step you confirm explicitly.
141+
142+
## What it bundles
143+
144+
One skill (`project-prospector`) plus reference agent-prompt templates and a
145+
trigger and task eval set. Read-only, general-purpose, no MCP, hooks, or
146+
scripts.
147+
148+
It complements `total-recall` (persistent operator memory) rather than
149+
duplicating it: prospector produces a one-shot ranked project census, not a
150+
memory profile.
151+
152+
You can also install from a local clone:
153+
154+
```text
155+
git clone https://github.com/88plug/project-prospector
156+
/plugin marketplace add ./project-prospector
157+
/plugin install project-prospector@project-prospector
158+
```
159+
160+
## Contributing
161+
162+
Issues and pull requests are welcome at
163+
[88plug/project-prospector](https://github.com/88plug/project-prospector). The
164+
[plugin-validate](https://github.com/88plug/project-prospector/actions/workflows/plugin-validate.yml)
165+
workflow checks the plugin manifest and skill structure on every push.
166+
167+
## License
168+
169+
[FSL-1.1-ALv2](LICENSE.md) © 2026 [88plug](https://github.com/88plug) —
170+
Functional Source License; converts to Apache 2.0 two years after each release.

‎mkdocs.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
site_name: Project Prospector
2+
site_description: >-
3+
A Claude Code plugin that catalogs and ranks everything you've built or
4+
sketched on a machine into a tiered ranking by idea-novelty and leverage.
5+
use_directory_urls: true
6+
7+
theme:
8+
name: material
9+
features:
10+
- navigation.sections # group nav by section, uses width well
11+
- navigation.top # back-to-top button
12+
- navigation.instant # SPA-style fast page loads
13+
- content.code.copy # copy button on code blocks (needs superfences below)
14+
- search.suggest
15+
palette:
16+
# Light/dark toggle that follows the OS preference by default.
17+
- media: "(prefers-color-scheme: light)"
18+
scheme: default
19+
toggle:
20+
icon: material/weather-night
21+
name: Switch to dark mode
22+
- media: "(prefers-color-scheme: dark)"
23+
scheme: slate
24+
toggle:
25+
icon: material/weather-sunny
26+
name: Switch to light mode
27+
28+
markdown_extensions:
29+
- admonition
30+
- attr_list
31+
- def_list
32+
- footnotes
33+
- tables
34+
- pymdownx.highlight # code highlighting (ships with mkdocs-material)
35+
- pymdownx.superfences # required for content.code.copy + nested fences
36+
- pymdownx.details # collapsible <details> admonitions
37+
- toc:
38+
permalink: true

0 commit comments

Comments
 (0)