Skip to content

Commit 76fce00

Browse files
manuelcorpasclaude
manuelcorpas
and
claude
committed
Initial release: Corpas Core Starter v0.2.0
AI-augmented cognitive decision support CLI with 17 commands: - Inbox triage, email drafting, document digest - Strategic reasoning with Three-Rule Framework - Task management with approval gates - Session handoff for continuity - Strategy-as-config (YAML) Optional Claude integration; works offline with structured prompts. 25 tests passing. MIT licensed. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
0 parents  commit 76fce00

17 files changed

Lines changed: 2125 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.10", "3.11", "3.12"]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Set up Python ${{ matrix.python-version }}
20+
uses: actions/setup-python@v5
21+
with:
22+
python-version: ${{ matrix.python-version }}
23+
24+
- name: Install dependencies
25+
run: |
26+
python -m pip install --upgrade pip
27+
pip install -e ".[dev]"
28+
29+
- name: Run tests
30+
run: pytest tests/ -v

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.venv/
2+
__pycache__/
3+
*.pyc
4+
*.egg-info/
5+
runtime/
6+
.env
7+
.DS_Store
8+
.claude/
9+
.pytest_cache/

‎AGENTS.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# AGENTS.md
2+
3+
This file describes how AI agents should interact with the Corpas Core Starter project.
4+
5+
## Overview
6+
7+
Corpas Core Starter is a cognitive decision-support framework. It manages prioritised tasks, logs decisions with reasoning, tracks shipped artifacts, and enforces human approval gates before outbound actions.
8+
9+
## Entry Points
10+
11+
The primary interface is the `corpas-core` CLI. All state is persisted in a local SQLite database at `runtime/corpas-core.db`.
12+
13+
### Initialise
14+
15+
```bash
16+
corpas-core init
17+
```
18+
19+
Creates the database and default strategy config. Safe to run multiple times.
20+
21+
### Autopilot Loop
22+
23+
```bash
24+
corpas-core autopilot --once
25+
```
26+
27+
Claims the highest-priority pending task and prints an execution brief. The agent should:
28+
1. Read the task description
29+
2. Produce a minimum viable output within a bounded time window
30+
3. If the task is marked `public_artifact=yes`, submit it for human approval before publishing
31+
4. Mark the task complete with an outcome summary
32+
33+
### Task Management
34+
35+
```bash
36+
corpas-core tasks --status pending # List available work
37+
corpas-core complete --task-id N --outcome "..." --artifact-url "..."
38+
```
39+
40+
### Approval Gates
41+
42+
Outbound actions (publishing, sending emails, external API calls) require explicit human approval:
43+
44+
```bash
45+
corpas-core gate --title "..." --content "..." # Queue for review
46+
corpas-core approvals --status pending # Check queue
47+
corpas-core resolve --item-id N --decision approved --note "..."
48+
```
49+
50+
**Never bypass the approval gate for public or outbound actions.**
51+
52+
### Daily Workflows
53+
54+
```bash
55+
corpas-core triage --file emails.txt # Classify emails, recommend actions, draft replies
56+
corpas-core draft --file email.txt # Draft a reply (--tone direct/warm/formal/decline/defer)
57+
corpas-core digest --file transcript.txt # Summarise document into actionable points
58+
corpas-core think "Should I accept?" # Reason about a decision using strategy context
59+
corpas-core filter "co-author request" # Apply Three-Rule Framework to incoming request
60+
```
61+
62+
All workflow commands accept input from `--file`, piped stdin, or interactive paste.
63+
64+
### Session Continuity
65+
66+
```bash
67+
corpas-core handoff # Save state to runtime/handoff.md
68+
corpas-core handoff --print # Print handoff to stdout
69+
corpas-core handoff --notes "Session summary here"
70+
```
71+
72+
The handoff document captures tasks, decisions, approvals, artifacts, and priorities. Read it at the start of each session for full context.
73+
74+
### Strategy Context
75+
76+
The agent's mission, priorities, and voice are defined in `config/strategy.template.yaml`. Read this file to understand what work matters and why.
77+
78+
```bash
79+
corpas-core brief # Human-readable summary
80+
corpas-core brief --json # Machine-readable summary
81+
```
82+
83+
## File Structure
84+
85+
```
86+
config/strategy.template.yaml # Mission and priorities (editable)
87+
runtime/corpas-core.db # Persistent state (auto-created)
88+
corpas_core/ # Python package
89+
cli.py # CLI commands
90+
state_manager.py # SQLite state persistence
91+
strategy_loader.py # YAML strategy parser
92+
```
93+
94+
## Conventions
95+
96+
- Tasks are ordered by priority (1 = highest). Claim the top pending task first.
97+
- Log decisions with context and reasoning. Future agents (and humans) will review them.
98+
- Public artifacts must have a URL and explicit title.
99+
- The `--json` flag on `brief` returns structured data for programmatic use.
100+
- Environment variable `CORPAS_CORE_HOME` sets the workspace root (defaults to current directory).
101+
102+
## Constraints
103+
104+
- Do not modify `runtime/corpas-core.db` directly. Use the CLI or StateManager API.
105+
- Do not publish, send, or deploy anything without passing through the approval gate.
106+
- Do not store API keys or secrets in this repository.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Manuel Corpas
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Corpas Core Starter
2+
3+
**AI-augmented cognitive decision support. Think clearer, ship faster, protect what matters.**
4+
5+
## The Problem
6+
7+
Knowledge workers are drowning. Not in tasks, but in decisions. Every email, meeting request, collaboration offer, and "quick favour" competes for the same finite cognitive budget. By the end of a typical week, you have been busy but cannot point to a single outcome that moved your mission forward.
8+
9+
AI tools promise "10x productivity." But speed without direction just produces more noise, faster.
10+
11+
## The Approach
12+
13+
Corpas Core is a different kind of tool. It does not automate your work. It enforces strategic discipline on your attention.
14+
15+
The system is built on three rules (from the [AI Fluency](https://github.com/manuelcorpas/ai-fluency) framework):
16+
17+
1. **Does this accelerate my core mission?** If no, decline or defer. "Interesting but tangential" is the enemy of focused impact.
18+
2. **Would accepting this delay my core deliverables?** Time is zero-sum. Protect your deep work hours.
19+
3. **If uncertain, build a prototype and test reality.** Ship something small. Reality provides feedback that speculation cannot.
20+
21+
Every task, decision, and approval passes through this filter.
22+
23+
## What It Does
24+
25+
Corpas Core Starter is a command-line tool that provides:
26+
27+
- **Inbox triage**: Classify emails by urgency and get draft replies in your voice. Pipe in emails or read from file.
28+
- **Email drafting**: Generate replies with configurable tone (direct, warm, formal, decline, defer) and word limits.
29+
- **Strategic reasoning**: Ask the system to evaluate decisions against your mission. "Should I accept this invitation?"
30+
- **Three-Rule Filter**: Run any incoming request through the framework. Get a PROCEED/DECLINE/DEFER/PROTOTYPE verdict.
31+
- **Document digest**: Summarise meeting transcripts, papers, or reports into actionable points with suggested tasks.
32+
- **Session handoff**: Capture full project state as a structured document. Resume seamlessly across tools and sessions.
33+
- **Approval gates**: Nothing gets published or sent without explicit human sign-off.
34+
- **Decision logging**: Every significant decision recorded with reasoning, so future-you can review and learn.
35+
- **Weekly shipping rhythm**: Track artifacts shipped per week. Did you ship something that matters, or did the week evaporate?
36+
- **Strategy-as-config**: Define your mission, priorities, and voice in a YAML file. The system holds you to them.
37+
38+
## Quick Start
39+
40+
```bash
41+
# Install
42+
pip install -e .
43+
44+
# Initialise (creates database and strategy config)
45+
corpas-core init
46+
47+
# See your mission and priorities
48+
corpas-core brief
49+
50+
# Triage your inbox (pipe in emails or use a file)
51+
cat emails.txt | corpas-core triage
52+
corpas-core triage --file inbox_export.txt
53+
54+
# Draft a reply to a specific email
55+
corpas-core draft --file email.txt --tone direct --sign-off "Dr Jane Smith"
56+
57+
# Reason about a decision
58+
corpas-core think "Should I accept this conference invitation in April?"
59+
60+
# Filter an incoming request using the Three-Rule Framework
61+
corpas-core filter "A colleague wants me to co-author a review paper on topic X"
62+
63+
# Summarise a meeting transcript into actionable points
64+
corpas-core digest --file meeting_notes.txt
65+
66+
# Add a task
67+
corpas-core add "Write first blog post" --priority 1 --public
68+
69+
# Claim next task and get an execution brief
70+
corpas-core autopilot --once
71+
72+
# Complete it
73+
corpas-core complete --task-id 1 --outcome "Published blog post" --artifact-url "https://..."
74+
75+
# Weekly review
76+
corpas-core review --local
77+
78+
# Save session state for continuity
79+
corpas-core handoff --notes "Finished draft, needs review"
80+
```
81+
82+
## Commands
83+
84+
**Daily workflows:**
85+
86+
| Command | Purpose |
87+
|---------|---------|
88+
| `triage` | Classify emails and recommend actions with draft replies |
89+
| `draft` | Draft a reply in your voice (`--tone direct/warm/formal/decline/defer`) |
90+
| `digest` | Summarise a document into actionable points with suggested tasks |
91+
| `think` | Reason about a question using your strategy as context |
92+
| `filter` | Apply the Three-Rule Framework to an incoming request |
93+
94+
**Task management:**
95+
96+
| Command | Purpose |
97+
|---------|---------|
98+
| `add` | Add a task (`--priority 1-5`, `--public`, `--description`) |
99+
| `tasks` | List tasks (filter by `--status pending/in_progress/done`) |
100+
| `autopilot --once` | Claim next high-priority task with execution brief |
101+
| `complete` | Mark task done with outcome and optional artifact URL |
102+
| `log` | Record a decision with context and reasoning |
103+
104+
**Governance and continuity:**
105+
106+
| Command | Purpose |
107+
|---------|---------|
108+
| `gate` | Queue something for human approval before publishing |
109+
| `approvals` | View approval queue |
110+
| `resolve` | Approve or reject a queued item |
111+
| `review` | Weekly strategic review (`--local` for offline, or LLM-powered) |
112+
| `brief` | Show mission, priorities, and snapshot (`--json` for machine output) |
113+
| `handoff` | Save full project state as a markdown document (`--print` for stdout) |
114+
115+
## LLM Reasoning
116+
117+
Set `ANTHROPIC_API_KEY` and install the optional dependency:
118+
119+
```bash
120+
pip install -e ".[llm]"
121+
export ANTHROPIC_API_KEY=sk-ant-...
122+
```
123+
124+
The `think`, `filter`, `review`, `triage`, `draft`, and `digest` commands will use Claude to reason in the context of your strategy. Without the API key, these commands output a structured prompt you can paste into any LLM.
125+
126+
## Configure For Your Purpose
127+
128+
Edit `config/strategy.template.yaml`:
129+
130+
```yaml
131+
mission:
132+
statement: "Your mission here."
133+
134+
priorities:
135+
- name: "Your first priority"
136+
definition_of_done: "How you know it is done."
137+
- name: "Your second priority"
138+
definition_of_done: "Measurable outcome."
139+
```
140+
141+
Customise your voice for email drafts:
142+
143+
```yaml
144+
voice:
145+
tone: "clear, concise, confident"
146+
style: "Claim-Justification-Implication"
147+
avoid:
148+
- "I hope this email finds you well"
149+
- "Sorry for the delay"
150+
- "hedging language"
151+
prefer:
152+
- "Active voice"
153+
- "Concrete next steps"
154+
- "Specific timelines"
155+
```
156+
157+
The system does not judge your mission. It holds you to it.
158+
159+
## The Full System Behind This
160+
161+
This starter is extracted from a working system that runs daily. The full Corpas Core manages:
162+
163+
- 2 AI agents across Telegram and WhatsApp, each with distinct personas
164+
- 8 scheduled job groups (research tracking, inbox triage, podcast intelligence, marking automation)
165+
- 14,000+ embedded documents in a personal knowledge base (notes, emails, papers)
166+
- Automated paper tracking, grant pipeline management, and weekly artifact shipping
167+
- Human-in-the-loop approval for every outbound action
168+
169+
One academic. Two agents. 500 lines of reusable scaffolding. The starter gives you the decision-support skeleton so you can build your own version.
170+
171+
## Design Principles
172+
173+
From [AI Fluency: A Practical Guide to Leveraging AI Chatbots for Academic and Professional Work](https://github.com/manuelcorpas/ai-fluency) by Dr Manuel Corpas:
174+
175+
- **You are the principal; AI is the agent.** Your expertise, values, and voice remain central. AI deploys them more efficiently.
176+
- **A 10x professional does not think 10x harder.** They think once and reuse that insight 10x. That is what systematic AI collaboration enables.
177+
- **Human-in-the-loop is not a limitation.** It is the design. Anthropic's research shows a 17% comprehension drop when people fully delegate to AI. The approval gate exists for a reason.
178+
- **Local-first, privacy-first.** All state in SQLite. No cloud dependency. No telemetry. Your decisions stay yours.
179+
- **Ship weekly or it did not happen.** Strategy without execution is delusion. The weekly artifact count is the accountability mechanism.
180+
181+
## What This Is Not
182+
183+
- Not a task manager. There are better ones. This is a strategic filter.
184+
- Not a chatbot. It reasons when asked, then gets out of the way.
185+
- Not a replacement for judgment. It is a system for recording, reviewing, and improving judgment over time.
186+
187+
## Requirements
188+
189+
- Python 3.10+
190+
- PyYAML (installed automatically)
191+
- Optional: `anthropic` SDK for LLM reasoning
192+
193+
## License
194+
195+
MIT. See [LICENSE](LICENSE).
196+
197+
## Author
198+
199+
[Dr Manuel Corpas](https://manuelcorpas.com) is a Senior Lecturer at the University of Westminster, Turing Fellow, and builder of AI-augmented research workflows. This tool is the operational companion to [AI Fluency](https://github.com/manuelcorpas/ai-fluency).

‎bin/bootstrap.sh‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
5+
cd "${ROOT_DIR}"
6+
7+
if [[ ! -d .venv ]]; then
8+
python3 -m venv .venv
9+
fi
10+
11+
source .venv/bin/activate
12+
pip install --upgrade pip
13+
pip install -e .
14+
corpas-core init
15+
16+
echo
17+
echo "Starter ready. Try:"
18+
echo " source .venv/bin/activate"
19+
echo " corpas-core autopilot --once"

0 commit comments

Comments
 (0)