Skip to content

Commit b626d0f

Browse files
saagpatelsaagpatel
authored
Merge pull request #56 from saagpatel/chore/remove-agent-scratchpad
chore: remove internal planning files and adopt proof packages
2 parents 0bd27aa + d6b52d2 commit b626d0f

36 files changed

Lines changed: 4170 additions & 32 deletions

‎CASE-STUDY.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Operator OS: A Multi-Agent Control Plane Over A Software Portfolio
2+
3+
Operator OS is a local-first control plane for AI-assisted builders: it turns a sprawling repo portfolio and multiple coding agents into verified truth, visible risk, and one operator-approved next move.
4+
5+
GitHub Repo Auditor is the truth engine behind the first public wedge. It began as a repository auditor, but the stronger product shape is a portfolio operating layer: one system that can say which projects are healthy, which are drifting, which are blocked, what changed, and what deserves attention next.
6+
7+
## Who This Is For
8+
9+
- Solo builders with dozens of repos and not enough trust in their own backlog.
10+
- Staff engineers and technical leads who need decision-grade visibility across experimental, internal, and production projects.
11+
- AI-native developers using Codex, Claude Code, ChatGPT, or similar tools across many workstreams.
12+
- Devtools teams studying how agent-created work should be verified, prioritized, and governed.
13+
14+
## The Problem
15+
16+
AI coding tools make it easier to start and modify projects. They do not automatically make it easier to know what is true afterward.
17+
18+
Once a portfolio has enough projects and enough agent-touched work, normal tools flatten the wrong things:
19+
20+
- `git log` shows activity, not whether the work matters.
21+
- GitHub alerts show risk, not which fix clears the most portfolio pain.
22+
- Notes and handoffs preserve intent, but can drift from the current repo state.
23+
- Agent transcripts are useful history, but they are not proof.
24+
- Dashboards can look polished while hiding stale or private source data.
25+
26+
Operator OS starts from a stricter premise: local evidence wins. Every product surface should be traceable back to files, commands, generated artifacts, or explicit operator approval.
27+
28+
## Before And After
29+
30+
| Before | After |
31+
| --- | --- |
32+
| A long list of repos | A portfolio truth snapshot with risk, readiness, context quality, and security posture |
33+
| Agent work scattered across chats | Agent provenance and follow-through visible in operator surfaces |
34+
| Weekly review rebuilt from memory | Weekly command-center artifacts generated from current audit facts |
35+
| Security alerts handled repo by repo | Advisory-grouped burndown showing the dependency bump that clears risk across repos |
36+
| Handoffs as stale prose | Restart-safe handoffs that say what was checked, what must be rechecked, and what not to touch |
37+
| Automation as blind trust | Dry-run-first proposals, explicit approvals, and evidence-backed execution gates |
38+
39+
## System Shape
40+
41+
```mermaid
42+
flowchart LR
43+
A["Local repos"] --> B["GitHub Repo Auditor"]
44+
B --> C["Portfolio truth JSON"]
45+
B --> D["Workbook / HTML / Markdown outputs"]
46+
C --> E["Portfolio Command Center"]
47+
D --> E
48+
E --> F["Operator decision"]
49+
F --> G["Manual or gated follow-through"]
50+
```
51+
52+
The public wedge keeps this system deliberately narrow:
53+
54+
- `GithubRepoAuditor` produces portfolio truth and weekly/operator artifacts.
55+
- `PortfolioCommandCenter` reads those artifacts and presents the operating view.
56+
- Fixture or sanitized data drives the public demo.
57+
- Private systems remain private implementation references, not public data sources.
58+
59+
The broader local machine adds other surfaces in private use:
60+
61+
- `bridge-db` for compact cross-agent receipts and state coordination.
62+
- `personal-ops` for private inbox, planning, approvals, and local operator workflows.
63+
- `notification-hub` for local event routing, review queues, and noise control.
64+
- `SecondBrain` for private synthesized knowledge and source-grounded lessons.
65+
- Codex and ChatGPT Pro workflow docs for advisory-only model review.
66+
67+
Those adjacent systems are useful because they prove the operating model under real pressure. They are not required for the public demo.
68+
69+
## What The Demo Shows
70+
71+
The public-safe demo should show the Portfolio Command Center running over fixture or sanitized portfolio truth:
72+
73+
1. A full portfolio table with risk, status, context quality, tool provenance, and security columns.
74+
2. A risk/security tab that turns raw alert counts into portfolio-level attention.
75+
3. A burndown tab that groups advisories by the fix that clears the most risk.
76+
4. Trend charts that show whether risk is improving or getting worse.
77+
5. A weekly digest that gives one headline, one decision, and one next move.
78+
79+
The private local proof package for the 2026-06-07 five-tab demo lives under `docs/demo-proof/2026-06-07/`. It proves the live local demo, but it is not the public publishing package because it may reveal real local portfolio details.
80+
81+
For public sharing, use the fixture-backed package under `docs/demo-proof/public-fixture/`.
82+
83+
## What Stays Private
84+
85+
The product should not expose raw local operating state. These surfaces are private by design:
86+
87+
- Local Codex sessions, memories, reports, hooks, secrets, config, and SQLite state.
88+
- Gmail, Calendar, Drive, task, approval, and daemon state from `personal-ops`.
89+
- Raw SecondBrain captures, conversation exports, vault history, and private notes.
90+
- Real Notion databases, project rows, tokens, API traces, and live write receipts.
91+
- `bridge-db` live SQLite contents, handoffs, snapshots, receipts, recall logs, and activity rows.
92+
- `notification-hub` events, Slack routing, local queue state, and review logs.
93+
- Private repo names, local absolute paths, branch state, and security findings unless they are intentionally sanitized.
94+
95+
The productizable asset is the pattern: local truth, bounded context, visible provenance, approval gates, and operator-facing decisions.
96+
97+
## Why It Is Hard To Copy
98+
99+
The moat is not a chart. Charts are easy.
100+
101+
The hard part is the lived-in operating discipline:
102+
103+
- One canonical truth contract feeding multiple views.
104+
- Generated artifacts that agree with each other instead of becoming separate stories.
105+
- Dry-run-first action flows that preserve human approval.
106+
- Explicit stale-state handling instead of cheerful lies.
107+
- Agent role boundaries: advisory models advise; local agents verify and execute.
108+
- Restart-safe handoffs that force the next session back to current evidence.
109+
- Private-by-default local operation with public-safe fixture demos.
110+
111+
Most products start with a dashboard and bolt trust on later. Operator OS starts with trust and lets the dashboard expose it.
112+
113+
## Public Wedge
114+
115+
The first wedge is Portfolio Command Center:
116+
117+
- simple enough to demo in 90 seconds;
118+
- grounded in concrete repo facts;
119+
- visually understandable to developers immediately;
120+
- impressive without needing private email, calendar, Notion, or agent transcripts;
121+
- extensible into the broader Operator OS story.
122+
123+
## Demo Links
124+
125+
- [90-second demo plan](DEMO-PLAN.md)
126+
- [Fixture demo source](fixtures/demo/sample-report.json)
127+
- [Public fixture proof package](docs/demo-proof/public-fixture/README.md)
128+
- [Private local demo proof package](docs/demo-proof/2026-06-07/README.md)
129+
- [Portfolio Command Center](../PortfolioCommandCenter/README.md)

‎DEMO-PLAN.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Portfolio Command Center Demo Plan
2+
3+
This is the public-safe demo plan for the Operator OS wedge.
4+
5+
The demo should prove one thing quickly: a serious builder can turn repo sprawl and agent-touched work into verified truth, visible risk, and one next move.
6+
7+
## Demo Thesis
8+
9+
Git history tells you what changed. Portfolio Command Center tells you what the change means.
10+
11+
## Demo Modes
12+
13+
Use one of two modes:
14+
15+
| Mode | Use for | Data source | Public-safe |
16+
| --- | --- | --- | --- |
17+
| Fixture mode | Public recording, docs, external sharing | `fixtures/demo/sample-report.json` via `make demo` | Yes |
18+
| Live local mode | Private operator proof and internal review | `output/portfolio-truth-latest.json` from the real local portfolio | No, unless redacted |
19+
20+
Default to fixture mode for anything public.
21+
22+
## Fixture Demo Setup
23+
24+
From this repo:
25+
26+
```sh
27+
make demo
28+
```
29+
30+
Expected outputs:
31+
32+
- `output/demo/demo-report.json`
33+
- `output/demo/demo-workbook.xlsx`
34+
- `output/demo/dashboard-*.html`
35+
- `output/demo/operator-control-center-demo.json`
36+
- `output/demo/operator-control-center-demo.md`
37+
- `output/demo/portfolio-truth-latest.json`
38+
- `output/demo/portfolio-warehouse.db`
39+
40+
Then launch the desktop shell from the sibling app:
41+
42+
```sh
43+
cd ../PortfolioCommandCenter
44+
pnpm install
45+
pnpm demo:desktop
46+
```
47+
48+
In the app header, set the output directory to:
49+
50+
```text
51+
../GithubRepoAuditor/output/demo
52+
```
53+
54+
If the recording needs live-shaped data, create a sanitized output directory first. Do not point a public recording at the private live `output/` directory.
55+
56+
## 90-Second Arc
57+
58+
| Time | Frame | Spoken line |
59+
| --- | --- | --- |
60+
| 0:00-0:10 | Portfolio table | "This is the problem AI builders are about to have: not one repo, but a portfolio of agent-touched work." |
61+
| 0:10-0:25 | Risk/context/status columns | "A commit timestamp is not enough. I need to know which projects are healthy, blocked, risky, stale, or worth ignoring." |
62+
| 0:25-0:42 | Risk + Security | "The control plane turns raw alerts and project facts into an attention map, so risk stops hiding in individual repos." |
63+
| 0:42-0:58 | Burndown | "The useful question is not just 'what is broken?' It is 'which fix clears the most portfolio pain?'" |
64+
| 0:58-1:12 | Trends | "Because it keeps history, I can tell whether the portfolio is improving or just getting noisier." |
65+
| 1:12-1:25 | Weekly Digest | "Every week, the system reduces the mess to one headline, one decision, and one next move." |
66+
| 1:25-1:30 | Return to Portfolio | "That is Operator OS: verified truth for builders using agents at portfolio scale." |
67+
68+
## Must-Land Product Points
69+
70+
- The app is reading generated artifacts, not a hand-maintained spreadsheet.
71+
- Portfolio truth, weekly digest, burndown, and charts come from the same evidence chain.
72+
- The operator remains in charge.
73+
- Public demo data is fixture-backed or sanitized.
74+
- Private local systems are implementation references, not public data sources.
75+
76+
## Do Not Show Publicly
77+
78+
- Real private repo names.
79+
- Local absolute paths under the user's home directory.
80+
- Real GitHub security alert details.
81+
- Notion database rows or page IDs.
82+
- Gmail, Calendar, Drive, Slack, or task data.
83+
- Codex sessions, memories, hook logs, or SQLite databases.
84+
- SecondBrain raw captures or conversation exports.
85+
- Tokens, cookies, env values, terminal scrollback, hostnames, or account settings.
86+
87+
## Redaction Checklist
88+
89+
Before publishing:
90+
91+
- [ ] Confirm the app is using `output/demo` or another sanitized output directory.
92+
- [ ] Confirm no private repo names are readable.
93+
- [ ] Confirm no terminal panes or local paths are visible.
94+
- [ ] Confirm no account names, tokens, hostnames, or private URLs are visible.
95+
- [ ] Confirm screenshots and video frames do not expose Notion, email, calendar, Slack, or SecondBrain.
96+
- [ ] Confirm any local live proof package is described as private/local evidence only.
97+
98+
## Verification Checklist
99+
100+
Run:
101+
102+
```sh
103+
make demo
104+
python scripts/validate_proof_package.py docs/demo-proof/public-fixture/proof-package.json
105+
```
106+
107+
For the desktop shell:
108+
109+
```sh
110+
cd ../PortfolioCommandCenter
111+
pnpm typecheck
112+
pnpm test
113+
pnpm build
114+
```
115+
116+
Visual verification is complete only after the app is opened against the fixture output and the Portfolio, Risk + Security, Burndown, Trends, and Weekly Digest tabs all render without private data.
117+
118+
## Final Public Framing
119+
120+
Use this closing sentence:
121+
122+
> Operator OS is the missing control plane for AI-assisted builders: it turns scattered agent work and repo sprawl into verified truth, visible risk, and one operator-approved next move.

‎README.md‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,10 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score
109109

110110
- Safe demo path: run `make demo` after a local clone to generate sample artifacts from the committed fixture without a GitHub token.
111111
- Demo fixture: [fixtures/demo/sample-report.json](fixtures/demo/sample-report.json)
112+
- Operator OS case study: [CASE-STUDY.md](CASE-STUDY.md)
113+
- Public-safe recording plan: [DEMO-PLAN.md](DEMO-PLAN.md)
114+
- Product brief: [docs/product/operator-os-product-brief.md](docs/product/operator-os-product-brief.md)
115+
- Public fixture proof package: [docs/demo-proof/public-fixture/README.md](docs/demo-proof/public-fixture/README.md)
112116
- Product modes: [docs/modes.md](docs/modes.md)
113117
- Web UI operator guide: [docs/audit-serve.md](docs/audit-serve.md)
114118
- CLI migration (flat → subcommand): [docs/audit-cli-migration.md](docs/audit-cli-migration.md)
@@ -192,6 +196,8 @@ pip install "github-repo-auditor[serve]"
192196
### Try the safe demo
193197

194198
The demo uses committed fixture data and writes only to `output/demo/`.
199+
Use this path for public recordings and screenshots. The live local portfolio
200+
output is private operator evidence unless it has been intentionally sanitized.
195201

196202
```bash
197203
git clone https://github.com/saagpatel/GithubRepoAuditor.git
@@ -204,8 +210,10 @@ Expected outputs include `output/demo/demo-report.json`,
204210
`output/demo/demo-workbook.xlsx`, `output/demo/dashboard-*.html`,
205211
`output/demo/operator-control-center-demo.json`,
206212
`output/demo/operator-control-center-demo.md`,
207-
`output/demo/portfolio-truth-latest.json`, and
208-
`output/demo/portfolio-warehouse.db`.
213+
`output/demo/portfolio-truth-latest.json`,
214+
`output/demo/weekly-command-center-sample-user-2026-04-12.json`,
215+
`output/demo/security-burndown-sample-user-2026-04-12.json`,
216+
`output/demo/pending-proposals.json`, and `output/demo/portfolio-warehouse.db`.
209217

210218
To browse the same fixture in the local web UI:
211219

@@ -214,6 +222,9 @@ pip install -e ".[serve]"
214222
audit serve --output-dir output/demo
215223
```
216224

225+
To record the Portfolio Command Center wedge from the same fixture, follow
226+
[DEMO-PLAN.md](DEMO-PLAN.md) and point the desktop app at `output/demo/`.
227+
217228
### Quick start (subcommand form)
218229

219230
```bash
@@ -431,6 +442,19 @@ Common fixes:
431442

432443
There is also a longer operator guide in [docs/operator-troubleshooting.md](docs/operator-troubleshooting.md).
433444

445+
## Proof Packages
446+
447+
Cross-repo done-state proof now uses `proof-package.v1`; see
448+
[docs/proof-package-contract.md](docs/proof-package-contract.md). The first
449+
concrete package is the PortfolioCommandCenter five-tab local demo proof at
450+
[docs/demo-proof/2026-06-07/proof-package.json](docs/demo-proof/2026-06-07/proof-package.json).
451+
452+
Validate a package with:
453+
454+
```bash
455+
python scripts/validate_proof_package.py docs/demo-proof/2026-06-07/proof-package.json
456+
```
457+
434458
## License
435459

436460
MIT

‎docs/demo-proof/2026-06-07/SUMMARY.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# PortfolioCommandCenter Demo Proof Package
2+
3+
This package proves the 2026-06-07 local five-tab PortfolioCommandCenter demo.
4+
GithubRepoAuditor is the evidence producer because it owns the portfolio truth
5+
and generated screenshots; PortfolioCommandCenter is the subject repo being
6+
demonstrated.
7+
8+
Status: passed.
9+
10+
Key proof points:
11+
12+
- Portfolio tab: 129 projects.
13+
- Risk + Security tab: 117 scanned repos and 63 with open high/critical alerts.
14+
- Burndown tab: advisory-grouped fix guidance.
15+
- Trends tab: risk and high/critical history charts.
16+
- Weekly Digest tab: current decision ends with `Start with codexkit.`
17+
18+
Use `proof-package.json` for the machine-readable claim-to-evidence map and
19+
`README.md` for the narrative proof summary.

0 commit comments

Comments
 (0)