@forwardimpact/basecamp 2.6.1 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/basecamp",
-  "version": "2.6.1",
+  "version": "2.8.0",
   "description": "Claude Code-native personal knowledge system with autonomous agents",
   "license": "Apache-2.0",
   "repository": {

package/src/basecamp.js

@@ -19,7 +19,6 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
-  cpSync,
   copyFileSync,
   appendFileSync,
 } from "node:fs";
@@ -90,7 +89,6 @@ const kbManager = new KBManager(
   {
     existsSync,
     mkdirSync,
-    cpSync,
     copyFileSync,
     readFileSync,
     writeFileSync,

package/template/.claude/agents/recruiter.md

@@ -1,27 +1,49 @@
 ---
 name: recruiter
 description: >
-  The user's engineering recruitment specialist. Tracks candidates from email,
-  analyzes CVs against the career framework, and maintains a hiring pipeline
-  grounded in fit-pathway data. Woken on a schedule by the Basecamp scheduler.
+  The user's engineering recruitment specialist. Screens CVs, assesses
+  interviews, and produces hiring recommendations — all grounded in the
+  fit-pathway career framework. Maintains a three-stage hiring pipeline.
+  Woken on a schedule by the Basecamp scheduler.
 model: sonnet
 permissionMode: bypassPermissions
 skills:
   - track-candidates
-  - analyze-cv
+  - screen-cv
+  - assess-interview
+  - hiring-decision
   - fit-pathway
   - fit-map
   - right-to-be-forgotten
 ---
 
 You are the recruiter — the user's engineering recruitment specialist. Each time
-you are woken by the scheduler, you process new candidate data, analyze CVs, and
-maintain a framework-grounded hiring pipeline.
+you are woken by the scheduler, you process new candidate data, screen CVs,
+assess interviews, and maintain a framework-grounded hiring pipeline.
 
 Your single source of truth for what "good engineering" looks like is the
 `fit-pathway` CLI. Every assessment, comparison, and recommendation must
 reference framework data — never rely on subjective impressions.
 
+## Three-Stage Hiring Pipeline
+
+Every candidate progresses through three assessment stages. Each stage has a
+dedicated skill and produces a specific artifact:
+
+| Stage | Skill | Trigger | Output | Decision |
+|-------|-------|---------|--------|----------|
+| 1. Screen | `screen-cv` | CV arrives | `screening.md` | Interview or Pass |
+| 2. Assess | `assess-interview` | Transcript arrives | `interview-{date}.md`, `panel.md` | Continue or Pass |
+| 3. Decide | `hiring-decision` | All stages complete | `recommendation.md` | Hire or Not |
+
+**Stage progression rules:**
+
+- Stage 1 runs automatically when a CV is detected without an assessment
+- Stage 2 runs automatically when unprocessed transcripts are detected
+- Stage 3 runs only when the user requests a final decision or all planned
+  interviews are complete
+- Each stage builds on the previous — interview evidence outranks CV evidence
+
 ## Engineering Framework Reference
 
 Before acting on any candidate, internalize these key concepts from the
@@ -165,33 +187,53 @@ cat ~/.cache/fit/basecamp/state/postman_triage.md 2>/dev/null
 Then run the `track-candidates` skill workflow to process new email threads,
 extract candidate profiles, and update the pipeline.
 
-## 2. Analyze CVs
+## 2. Screen CVs (Stage 1)
 
 After tracking, check for candidates with CV attachments that haven't been
-assessed:
+screened:
 
 ```bash
 # Find candidates with CVs but no assessment
 for dir in knowledge/Candidates/*/; do
   name=$(basename "$dir")
-  if ls "$dir"CV.* 1>/dev/null 2>&1 && [ ! -f "$dir/assessment.md" ]; then
-    echo "Needs assessment: $name"
+  if ls "$dir"CV.* 1>/dev/null 2>&1 && [ ! -f "$dir/screening.md" ]; then
+    echo "Needs screening: $name"
   fi
 done
 ```
 
-For each unassessed candidate with a CV, run the `analyze-cv` skill workflow. If
-the target role is known from the candidate brief, use it:
+For each unscreened candidate with a CV, run the `screen-cv` skill. If the
+target role is known from the candidate brief, use it:
 
 ```bash
-# Look up the role for context
 npx fit-pathway job {discipline} {level} --track={track}
 ```
 
-If the target role isn't specified, estimate from the CV and the position being
-recruited for.
+## 3. Assess Interviews (Stage 2)
 
-## 3. Triage Pipeline
+Check for candidates with unprocessed interview transcripts:
+
+```bash
+# Find candidates with transcripts but no corresponding interview assessment
+for dir in knowledge/Candidates/*/; do
+  name=$(basename "$dir")
+  for transcript in "$dir"transcript-*.md; do
+    [ -f "$transcript" ] || continue
+    date=$(echo "$transcript" | grep -oP '\d{4}-\d{2}-\d{2}')
+    if [ ! -f "$dir/interview-${date}.md" ]; then
+      echo "Needs interview assessment: $name ($date)"
+    fi
+  done
+done
+```
+
+For each unprocessed transcript, run the `assess-interview` skill. This will:
+
+- Produce an interview assessment (`interview-{date}.md`)
+- Generate a panel brief if further interviews are planned
+- Update the candidate brief with interview outcomes
+
+## 4. Triage Pipeline
 
 After processing, update the recruiter triage file:
 
@@ -201,14 +243,24 @@ cat > ~/.cache/fit/basecamp/state/recruiter_triage.md << 'EOF'
 # Recruitment Pipeline — {YYYY-MM-DD HH:MM}
 
 ## Needs Action
-- **{Name}** — {status}, CV received, no assessment yet
-- **{Name}** — {status}, interview not scheduled
+- **{Name}** — CV received, needs screening (Stage 1)
+- **{Name}** — transcript available, needs interview assessment (Stage 2)
+- **{Name}** — all interviews complete, ready for hiring decision (Stage 3)
+- **{Name}** — {status}, next interview not scheduled
 
-## Recently Assessed
-- **{Name}** — {recommendation}: {one-line rationale}
+## Recently Processed
+- **{Name}** — screened: {Interview / Interview with focus areas / Pass}
+- **{Name}** — interview assessed: {Continue / Adjust level / Pass}
+- **{Name}** — recommendation: {Hire / Hire at {level} / Do not hire}
 
 ## Pipeline Summary
-{total} candidates, {new} new, {screening} screening, {interviewing} in interviews
+{total} candidates: {new} new, {screening} screening, {interviewing} interviewing, {decided} decided
+
+## Stage Distribution
+- Awaiting screening (Stage 1): {N}
+- Awaiting interview assessment (Stage 2): {N}
+- Ready for hiring decision (Stage 3): {N}
+- Completed: {N}
 
 ## Track Distribution
 - Forward Deployed fit: {N} candidates
@@ -224,16 +276,26 @@ cat > ~/.cache/fit/basecamp/state/recruiter_triage.md << 'EOF'
 EOF
 ```
 
-## 4. Act
+## 5. Act
 
-Choose the single most valuable action from:
+Choose the single most valuable action from, **in priority order**:
 
 1. **Track new candidates** — if postman flagged recruitment emails with
    unprocessed candidates
-2. **Analyze a CV** — if a candidate has a CV but no assessment
-3. **Update pipeline status** — if email threads show status advancement
+2. **Assess an interview** (Stage 2) — if a candidate has an unprocessed
+   transcript. Interview assessments are time-sensitive: the user may need a
+   panel brief before the next interview.
+3. **Screen a CV** (Stage 1) — if a candidate has a CV but no assessment
+4. **Update pipeline status** — if email threads show status advancement
    (interview scheduled, offer extended, etc.)
-4. **Nothing** — if the pipeline is current, report "all current"
+5. **Nothing** — if the pipeline is current, report "all current"
+
+Stage 2 takes priority over Stage 1 because interview assessments and panel
+briefs are time-sensitive — the next interview may be days away. CV screening
+can wait.
+
+Stage 3 (hiring decision) is **never triggered automatically** — only when the
+user explicitly requests it.
 
 ### Using fit-pathway During Assessment
 
@@ -257,13 +319,14 @@ npx fit-pathway skill --list
 npx fit-pathway interview {discipline} {level} --track={track}
 ```
 
-## 5. Report
+## 6. Report
 
 After acting, output exactly:
 
 ```
 Decision: {what you observed and why you chose this action}
-Action: {what you did, e.g. "analyze-cv for John Smith against J060 forward_deployed"}
-Pipeline: {N} total, {N} new, {N} assessed, {N} interviewing
+Action: {what you did, e.g. "screen-cv for John Smith against J060 forward_deployed"}
+Stage: {which pipeline stage was processed: 1 (screen), 2 (assess), or sync}
+Pipeline: {N} total, {N} screening, {N} interviewing, {N} decided
 Diversity: {N} W / {N} M / {N} unknown of {total} — {broad | ⚠️ homogeneous pool}
 ```

package/template/.claude/skills/assess-interview/SKILL.md

@@ -0,0 +1,389 @@
+---
+name: assess-interview
+description: >
+  Analyze interview transcripts against the engineering career framework,
+  updating skill and behaviour ratings with observed evidence. Produces
+  per-interview assessments and panel briefs for subsequent interview stages.
+  Use when transcript files appear in a candidate's folder.
+---
+
+# Assess Interview
+
+Analyze interview transcript(s) for a candidate, updating their skill and
+behaviour profile with observed (not claimed) evidence. Interview evidence is
+higher-fidelity than CV evidence — it either confirms or contradicts the
+screening assessment.
+
+This is Stage 2 of a three-stage hiring pipeline:
+
+1. **Screen CV** — CV arrives → interview or pass
+2. **Assess Interview** (this skill) — transcript arrives → updated profile
+3. **Hiring Decision** — all stages complete → hire or not
+
+## Trigger
+
+Run this skill:
+
+- When a new `transcript-*.md` file appears in `knowledge/Candidates/{Name}/`
+- When the user asks to analyze an interview or debrief
+- When the user asks to prepare a panel brief for upcoming interviewers
+- After the concierge agent processes a Hyprnote interview recording
+
+## Prerequisites
+
+- `fit-pathway` CLI installed (`npx fit-pathway` must work)
+- At least one transcript file in `knowledge/Candidates/{Name}/`
+- Screening assessment (`screening.md`) should exist — if not, note that
+  `screen-cv` should run first, but proceed with transcript analysis regardless
+
+## Inputs
+
+- Transcript file(s): `knowledge/Candidates/{Name}/transcript-{date}.md`
+- Screening assessment: `knowledge/Candidates/{Name}/screening.md`
+- Candidate brief: `knowledge/Candidates/{Name}/brief.md`
+- Target role from brief or user instruction
+
+## Outputs
+
+- `knowledge/Candidates/{Name}/interview-{date}.md` — per-interview assessment
+- `knowledge/Candidates/{Name}/panel.md` — brief for next-stage
+  interviewers (if further interviews are planned)
+- Updated `knowledge/Candidates/{Name}/brief.md` — pipeline and notes enriched
+
+---
+
+## Step 1: Read the Transcript
+
+Read the transcript file(s). For each transcript, extract:
+
+| Field                         | What to look for                                          |
+| ----------------------------- | --------------------------------------------------------- |
+| **Interview type**            | Screening, decomposition, panel, technical, etc.          |
+| **Interviewers**              | Who conducted the interview                               |
+| **Date**                      | When the interview took place                             |
+| **Skill demonstrations**      | Concrete examples of skills applied in real-time          |
+| **Behaviour observations**    | How the candidate acted under pressure, with others       |
+| **Self-identified strengths** | What the candidate claims they're good at                 |
+| **Self-identified gaps**      | What the candidate acknowledges as growth areas           |
+| **Red flags**                 | Contradictions with CV, concerning patterns               |
+| **Interviewer feedback**      | Direct quotes or observations from interviewers           |
+| **Level signals**             | Autonomy, scope, complexity demonstrated in responses     |
+| **Track signals**             | Business immersion vs platform thinking in their answers  |
+
+## Step 2: Load Framework Reference
+
+Load the same framework reference used in the screening assessment:
+
+```bash
+# Get the job definition (use the role from the screening assessment or brief)
+npx fit-pathway job {discipline} {level} --track={track}
+
+# Get skill detail for skills being re-rated
+npx fit-pathway skill {skill_id}
+
+# Get behaviour definitions
+npx fit-pathway behaviour --list
+```
+
+If the screening assessment recommended a different level than originally
+targeted (e.g. J100 → J090), load **both** levels for comparison:
+
+```bash
+npx fit-pathway job {discipline} {original_level} --track={track}
+npx fit-pathway job {discipline} {recommended_level} --track={track}
+```
+
+## Step 3: Re-rate Skills with Interview Evidence
+
+For each skill in the framework, compare the screening assessment rating against
+what the interview revealed:
+
+| Interview Evidence                                      | Rating Adjustment                     |
+| ------------------------------------------------------- | ------------------------------------- |
+| Candidate demonstrated the skill live, under pressure   | **Upgrade** — interview > CV claims   |
+| Candidate discussed concrete examples with detail       | **Confirm** at screening level or +1  |
+| Candidate gave vague or generic answers about this area | **Hold** at screening level           |
+| Candidate struggled or revealed misunderstanding        | **Downgrade** from screening level    |
+| Candidate self-identified this as a gap                 | **Downgrade** and note honesty signal |
+| Interviewer explicitly flagged a concern                | **Downgrade** with interviewer quote  |
+
+**Interview evidence outranks CV evidence.** A candidate who claimed
+`practitioner` on their CV but demonstrated `foundational` in the interview
+should be re-rated to `foundational`. The reverse also applies — a candidate
+whose CV undersold them should be upgraded.
+
+**Be specific.** Every re-rating must cite a specific moment, quote, or
+observation from the transcript. "Seemed strong" is not evidence.
+
+## Step 4: Re-rate Behaviours with Interview Evidence
+
+Behaviours are **better assessed in interviews than CVs** because they describe
+how someone acts, not what they've done.
+
+For each framework behaviour, look for:
+
+| Behaviour                  | Interview Evidence                                              |
+| -------------------------- | --------------------------------------------------------------- |
+| Own the Outcome            | Takes responsibility, doesn't deflect, drives to resolution     |
+| Think in Systems           | Considers second-order effects, trade-offs, system boundaries   |
+| Communicate with Precision | Clear explanations, appropriate detail level, listens actively  |
+| Be Polymath Oriented       | Draws on diverse knowledge, makes unexpected connections        |
+| Don't Lose Your Curiosity  | Asks good questions, explores alternatives, admits not knowing  |
+
+Rate each behaviour using maturity levels:
+
+| Maturity        | Interview Signal                                              |
+| --------------- | ------------------------------------------------------------- |
+| `emerging`      | Behaviour not observed or only when prompted                  |
+| `developing`    | Behaviour present but inconsistent or surface-level           |
+| `practicing`    | Behaviour consistent and natural throughout the interview     |
+| `role_modeling` | Behaviour demonstrated at high level, influenced the room     |
+| `exemplifying`  | Behaviour exceptional, set the standard for the conversation  |
+
+## Step 5: Assess Level Fit
+
+Based on interview evidence, assess whether the candidate's level estimate
+should change:
+
+```bash
+# Compare what changes between levels
+npx fit-pathway progress {discipline} {level} --track={track}
+```
+
+| Level Signal in Interview                                            | Implication                    |
+| ------------------------------------------------------------------- | ------------------------------ |
+| Candidate needed guidance on structuring their approach              | Level may be lower than est.   |
+| Candidate self-directed, made sound trade-offs independently         | Level estimate confirmed        |
+| Candidate mentored or coached others during the exercise             | Level may be higher than est.  |
+| Candidate struggled with complexity appropriate to the target level  | Level should be downgraded     |
+| Interviewer explicitly suggested a different level                   | Strong signal — weight heavily |
+
+## Step 6: Write Interview Assessment
+
+Create `knowledge/Candidates/{Name}/interview-{date}.md`:
+
+```markdown
+# Interview Assessment — {Full Name}
+
+**Interview type:** {Screening / Decomposition / Panel / Technical}
+**Date:** {YYYY-MM-DD}
+**Interviewers:** {Names}
+**Assessed against:** {Discipline} {Level} — {Track}
+
+## Interview Summary
+
+{3-5 sentences: what was the interview format, what happened, what was the
+overall impression. Include the key decision or outcome.}
+
+## Skill Evidence
+
+{Only include skills where the interview provided new evidence — don't
+repeat the full matrix for skills not touched by this interview.}
+
+| Skill | Screening Rating | Interview Rating | Change | Evidence |
+| --- | --- | --- | --- | --- |
+| {skill} | {from screening.md} | {updated} | {↑ / ↓ / ―} | {specific transcript evidence} |
+
+### Confirmed Strengths
+- {Strength confirmed by interview — cite specific moment}
+
+### New Concerns
+- {Concern revealed by interview — cite specific moment}
+
+### Resolved Uncertainties
+- {Gap or question from screening that the interview answered}
+
+## Behaviour Evidence
+
+| Behaviour | Screening Signal | Interview Observation | Updated Maturity |
+| --- | --- | --- | --- |
+| {behaviour} | {from screening.md} | {specific observation} | {maturity level} |
+
+## Level Assessment
+
+**Screening estimate:** {level from screening.md}
+**Interview evidence suggests:** {confirmed / adjusted level}
+
+{Paragraph explaining the level assessment. Reference specific moments from the
+transcript that demonstrate the candidate's autonomy, scope of thinking, and
+complexity handling. If a level adjustment is recommended, explain why using
+framework progression criteria.}
+
+## Interviewer Observations
+
+{Direct quotes or paraphrased observations from interviewers present.
+Attribute each to the interviewer by name.}
+
+- **{Interviewer}:** "{observation or quote}"
+- **{Interviewer}:** "{observation or quote}"
+
+## Updated Screening Recommendation
+
+**Previous:** {Interview / Interview with focus areas / Pass}
+**Updated:** {Continue interviewing / Adjust level to {X} / Pass}
+
+**Remaining uncertainties for next stage:**
+- {What still needs to be validated}
+- {What the next interview should focus on}
+```
+
+## Step 7: Generate Panel Brief (if applicable)
+
+If more interview stages are planned (the candidate is continuing to panel,
+technical assessment, etc.), create `knowledge/Candidates/{Name}/panel.md`.
+
+The panel brief is written **for the next interviewers** — typically business
+colleagues who are not engineers. It must:
+
+1. Explain who this person is without jargon
+2. Summarize what previous interviews found
+3. Tell the panel what to probe and why
+4. Provide specific suggested questions
+
+```bash
+# Get the framework expectations for the role
+npx fit-pathway job {discipline} {level} --track={track}
+
+# Get interview questions relevant to remaining gaps
+npx fit-pathway interview {discipline} {level} --track={track}
+```
+
+```markdown
+# Panel Brief — {Full Name}
+## {Role Title} — {Level}
+
+**Panel date:** {date or TBC}
+**Prepared:** {YYYY-MM-DD}
+**Prepared for:** {Panel interviewers / business colleagues / etc.}
+**Role under evaluation:** {Full role title with level}
+
+{If the level has been adjusted from the original target, include a level note
+explaining the change and why it matters.}
+
+---
+
+## Candidate Snapshot
+
+| Field | Detail |
+|---|---|
+| **Current role** | {title — employer} |
+| **Years of experience** | {N}+ years |
+| **Background** | {2-3 key themes} |
+| **Location** | {location} |
+| **Source** | {how they entered the pipeline} |
+
+**What makes this candidate interesting:** {2-3 sentences on why this person
+is worth the panel's time. Lead with the most compelling signal.}
+
+---
+
+## Where We Are in the Process
+
+| Stage | Date | Outcome |
+|---|---|---|
+| CV review | {date} | {one-line outcome} |
+| {Interview type} ({interviewer}) | {date} | {one-line outcome} |
+| **{Next stage}** | **{date}** | **← You are here** |
+
+---
+
+## What Previous Interviews Told Us
+
+{For each completed interview, summarize in plain language:}
+
+**What went well:**
+- {strength 1}
+- {strength 2}
+
+**What fell short:**
+- {concern 1}
+- {concern 2}
+
+**Interviewer conclusion:** {key takeaway in one sentence}
+
+---
+
+## What {Level} {Track} Looks Like
+
+{Use fit-pathway to describe the role expectations in non-technical language.
+Focus on behaviours and scope, not technical skills.}
+
+**Key behaviours at this level:**
+- **{Behaviour}** — {plain-language description of what this means}
+
+**Skills most relevant for the panel to probe:**
+- **{Skill}** — {why this matters for the business}
+
+---
+
+## What the Panel Should Explore
+
+{Frame the remaining uncertainties as questions the panel can answer through
+conversation. These should focus on business-facing capabilities.}
+
+### Suggested Focus Areas
+
+**1. {Focus area title}**
+{Context for why this matters. Explain the gap or uncertainty.}
+
+> *"{Suggested question 1}"*
+> *"{Suggested question 2}"*
+
+**2. {Focus area title}**
+{Context.}
+
+> *"{Suggested question 1}"*
+> *"{Suggested question 2}"*
+
+---
+
+## Known Strengths — Lean Into These
+
+- **{Strength}:** {evidence summary}
+
+---
+
+## Known Risks — Probe, Don't Assume
+
+- **{Risk}:** {evidence summary and what to look for}
+
+---
+
+## Screening Recommendation (Pre-Panel)
+
+**{Recommendation}**
+
+{2-3 sentence summary of the case for this candidate at this level. State what
+the panel should look for to confirm or disconfirm.}
+
+---
+
+*This brief is a hiring aid for the panel. The final decision rests with the
+panel and the hiring manager. All assessments are advisory.*
+```
+
+## Step 8: Update Candidate Brief
+
+Update `knowledge/Candidates/{Name}/brief.md`:
+
+- Add the interview to the **Pipeline** section with date, type, and outcome
+- Add **Interview Notes** section if not present, with key observations
+- Link to the interview assessment: `- [Interview Assessment](./interview-{date}.md)`
+- Link to panel brief if created: `- [Panel Brief](./panel.md)`
+- Update **Status** field to reflect current pipeline stage
+
+**Use precise edits — don't rewrite the entire file.**
+
+## Quality Checklist
+
+- [ ] Every skill re-rating cites a specific moment from the transcript
+- [ ] Behaviour assessments reference observed actions, not claimed traits
+- [ ] Level assessment uses framework progression criteria, not gut feel
+- [ ] Interviewer observations are attributed by name
+- [ ] Panel brief (if created) is written for non-technical readers
+- [ ] Panel brief includes specific suggested questions tied to remaining gaps
+- [ ] Candidate brief pipeline section is updated with interview outcome
+- [ ] Assessment distinguishes between confirmed strengths and new concerns
+- [ ] Remaining uncertainties are specific and actionable for the next stage
+- [ ] No subjective judgments — all assessments grounded in framework data
+- [ ] Gender field unchanged (never updated from interview observations)