A foreword is the part of the book written before the story. Foreword has you write your career's announcement first, then collects the evidence that makes it true.
Status: local alpha. Foreword is a local-first career evidence system for AI assistants. It turns weekly work into sourced achievements, feedback, and review packets using a private markdown vault and a skill pack. No account, database, app, or connector is required.
If you only read one file after this README, use docs/START_HERE.md. It is the assistant-first path with a copy-paste prompt and recovery steps.
Open this repo in your preferred AI assistant, such as Claude, Copilot, Codex, VS Code chat, or any assistant that can read and edit local files. Paste:
You are in the Foreword repository.
Read README.md and docs/START_HERE.md.
Use repo-scoped Foreword skills if your assistant supports them; otherwise read skills/setup/SKILL.md and the shared contracts in skills/_shared/.
Create my private Foreword vault in ./local-vault inside this repository.
Run setup with me, keep my data private, and do not store connector secrets.
After setup, help me capture one recent win or schedule the first weekly 15-minute meeting with myself.
That is the whole start. The assistant reads the docs, creates a private vault, and runs a short interview (about ten minutes) for your goals, narrative, and privacy defaults. You do not need to be an AI expert or a developer; if the assistant can work with local files, it can guide the workflow. From then on the habit is one weekly 15-minute meeting with yourself.
local-vault/ lives inside this repository on purpose and is ignored by git. That lets you see exactly what Foreword is putting in your vault while keeping private career data out of commits. No terminal, account, database, or app is required; the fallback paths are in docs/QUICKSTART.md.
Foreword helps you stop reconstructing your career from memory. It gives you a small evidence loop for the career rituals that usually happen too late:
- Weekly: a 15-minute meeting with yourself that captures work, wins, feedback, gaps, goal movement, and one if-then plan.
- Monthly: after the weekly meeting, compile the month's best achievements and ask for one useful feedback signal.
- Quarterly: after the weekly meeting, reset goals, review the narrative, and audit the career PR/FAQ evidence gaps.
- Yearly or review season:
/packetturns the accumulated evidence into a promo doc draft, self-review, resume bullets, or interview stories.
The core idea: your career story is a press release written too late. Whether the goal is a promotion, a new job, or some other move you're building toward, Foreword adapts Working Backwards: write the future announcement, tag the claims it makes, then let weekly evidence prove or revise the story.
Working Backwards starts from the customer and the desired outcome before building anything. Foreword asks the same questions about your career, and each one has a skill that answers it:
| Working Backwards question | Career translation | Where Foreword answers it |
|---|---|---|
| Who is the customer? | You, plus the decision-maker who must say yes: manager, promo committee, hiring manager, or market | setup interview; the PR/FAQ customer section |
| What is their problem or opportunity? | The role you envision, and the pain that makes it worth funding | prfaq press release; narrative direction |
| Why this solution over the alternatives? | Your strengths and honest gaps, against the people they could pick instead | narrative strengths and gaps; the reasons-not-to FAQ |
| What does the experience look like? | The development journey: the activities that close each gap, week by week | goals with if-then plans; weekly checkin and capture |
| How is success defined and measured? | Claims with evidence statuses, goal movement, and a packet that survives scrutiny | claim registry; monthly achievements; packet |
The cadence keeps the model honest: the weekly 15-minute self-meeting feeds the worklog, the monthly compile curates it, the quarterly review realigns the story, and the yearly or review-season packet compiles it. See docs/CADENCE.md for the full rhythm.
For the practical one-page version, see docs/MENTAL_MODEL.md. It includes the five Working Backwards questions, supporting prompts, and the evidence loop.
flowchart TD
A[Open with any file-aware AI assistant] --> B[Agent explains Foreword and finds the skills]
B --> C[Agent creates or locates ./local-vault]
C --> D[Verify local-vault is ignored by git]
D --> E[Run setup]
E --> F[Choose evidence path: connected, inbox, or guided]
F --> G[Capture wins anytime]
F --> H[Run weekly self-meeting]
H --> I[Monthly compile]
I --> J[Quarterly reset]
J --> K[Yearly or review-season packet]
The first move is choosing the tool you already use. The assistant then creates or uses ./local-vault/ inside the repo, checks that it is ignored, and guides the weekly evidence loop. For the complete route tree and recovery paths, see docs/USER_JOURNEY.md.
From the repo root on Windows:
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\new-vault.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-skills.ps1On macOS or Linux:
cp -r vault-template local-vault
bash scripts/install-skills.shThen keep your assistant in this repo and run setup against ./local-vault/: /setup in Claude Code, $setup in Codex, or the no-install prompt in docs/USING_SKILLS.md.
| Skill | Cadence | Purpose |
|---|---|---|
/setup / $setup |
once | Create the vault context, goals, narrative, claim registry, cadence, tier, and optional calendar preference |
/capture / $capture |
anytime | File one win, quote, metric, artifact, or observed outcome |
/checkin / $checkin |
weekly | Run the 15-minute meeting with yourself |
/achievements / $achievements |
monthly | Curate the month's best evidence |
/feedback / $feedback |
monthly | Draft narrow feedback asks and log replies verbatim |
/goals / $goals |
quarterly | Set or revise 1-3 goals with WOOP and if-then plans |
/narrative / $narrative |
quarterly | Compare the career story against collected evidence |
/prfaq / $prfaq |
quarterly | Draft or revise the career PR/FAQ and claim registry |
/coach / $coach |
on demand | Give career advice grounded in the vault |
/packet / $packet |
yearly or review season | Compile a promo, self-review, resume packet, or interview stories |
/retrospective / $retrospective |
monthly-ish | Improve the system itself from usage friction |
Claude Code discovers project skills from .claude/skills/. Codex discovers repo skills from .agents/skills/. This repo includes both mirrors so the assistant can use Foreword from the repo without a separate install. The source of truth remains skills/, and the validator checks that the mirrors match.
The same vault and skills work at three levels:
- Tier A, Connected: if your assistant already has authorized read-only Gmail, Slack, Calendar, Drive, or MCP/plugin access, Foreword can use those sources to prefill a digest. You confirm before anything is written.
- Tier B, Inbox drop: copy emails, Slack/Teams snippets, screenshots, meeting notes, or exported calendar context into
inbox/. The assistant parses and files only after confirmation. - Tier C, Guided: no connectors and no files, just the weekly interview. This is still a first-class path, not a fallback.
Details and safety rules live in docs/TIERS.md and docs/PRIVACY.md.
- vault-template/ is the starter private vault.
- skills/ is the source skill catalog.
- .claude/skills/ and .agents/skills/ are repo-scoped assistant mirrors.
- scripts/ creates vaults and installs personal/project skill copies.
- examples/tier-c-example-vault/ shows a fictional product-operations vault.
- docs/QUICKSTART.md, docs/USER_JOURNEY.md, docs/AGENT_SETUP.md, and docs/USING_SKILLS.md explain usage paths.
- docs/START_HERE.md, docs/CADENCE.md, and docs/MENTAL_MODEL.md are the fastest user-facing entry points.
- docs/SCHEMA.md, docs/PRIVACY.md, docs/PRINCIPLES.md, and docs/QUALITY_GATES.md define the public contracts and safety rails.
Validate everything with:
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\validate-repo.ps1- Evidence over vibes. Quotes, metrics, artifacts, and dated observations beat self-ratings.
- Files over apps. Plain markdown stays portable across Obsidian, VS Code, terminals, and assistants.
- Connectors without lock-in. Live sources are optional, read-only, and never write to the vault without confirmation.
- Nobody excluded. Connected accounts, inbox drops, and guided interviews all produce the same evidence shape.
- Review season starts now. The packet should be compiled from evidence, not reconstructed from panic.