Team Workflow and Task Tracking

Date: 2026-02-28 Status: Draft — open for team discussion

---

Problem Statement

The team (CEO, CTO, one developer) uses AI-assisted development heavily. This creates a coordination problem:

1. Duplicate work — two sessions start the same research or implementation without knowing the other exists.
2. Invisible progress — work happens in Claude Code sessions, local branches, and documentation files that nobody else sees until a PR or message.
3. Three work categories mix together — research, implementation, and infrastructure have different lifecycles but live in the same backlog.
4. The developer communicates infrequently — passive tracking (not active standups) is needed to keep everyone aligned.

---

Recommendation: GitHub Projects + Slack Channel + Lightweight Automation

One system of record (GitHub Projects), one communication channel (Slack), one bot connecting them.

Why Not Notion Alone

Notion is good for product specs and long-form documents (Primer, Clarity spec). It is not good for task tracking in a dev-heavy workflow because:

• No native git integration (PRs, branches, commits don't link automatically)
• No automated status updates from CI/CD or code activity
• Context-switching cost: developers already live in terminal + GitHub

Notion keeps its current role: product vision, specs, and synced documents. Task tracking moves to GitHub.

Why Not Documentation Files Alone

The current PLAN-TRACKER.md is useful as a snapshot but it's manually maintained — it drifts from reality within hours. Nobody updates a markdown file mid-session.

Documentation keeps its current role: detailed plans, research, architecture decisions. Status tracking moves to GitHub.

Why GitHub Projects

• Tasks link directly to PRs, branches, and commits — status updates happen automatically when PRs merge.
• GitHub Issues support labels, assignees, and milestones — native to the workflow.
• Free for the team size. No new tool to learn.
• GitHub Actions can post to Slack on issue state changes.
• The developer already interacts with GitHub (even if rarely with Slack).

---

Work Categories as GitHub Project Views

One GitHub Project with three filtered views:

1. Research

Tasks that produce documents, not code. Output is a review, feasibility study, or analysis.

Field	Example
Label	research
Output	Markdown doc in sv0-documentation/
Done when	Document exists and is linked in the issue
Example	"Research execution evidence feasibility for Entra sign-in logs"

2. Implementation

Tasks that produce code changes. Output is a PR.

Field	Example
Label	implementation
Output	PR in sv0-platform or sv0-connectors
Done when	PR merged and tests pass
Example	"Add evidence grade computation to path materializer"

3. Infrastructure

Tasks that affect deployment, CI/CD, environments, or tooling. Output is configuration or operational change.

Field	Example
Label	infrastructure
Output	Config change, deployment, or runbook update
Done when	Change is live and verified
Example	"Set up GitHub Actions for Claude CI auto-fix"

---

Duplicate Work Prevention

The core problem: two people (or two Claude Code sessions) start the same task independently.

Rule 1: Claim Before Starting (Automated for AI Sessions)

No human creates issues manually. Claude Code agents do it automatically via two mechanisms:

A. UserPromptSubmit hook (.claude/hooks/check-github-issues.sh) On every substantive prompt, the hook queries GitHub for open issues across all SecurityV0 repos and injects them into the agent's context. The agent sees what's already in progress before starting work.

B. AGENTS.md instructions The agent instructions include a "Task Tracking" section that tells every Claude Code session to:

1. Search for existing issues matching the task
2. If one exists, assign itself and mention it to the user
3. If none exists, create one with gh issue create and assign @me
4. Close the issue when work is complete

This means the developer just describes what they want. The agent checks for conflicts and creates the tracking issue automatically.

For human-only work (rare): create the issue manually via gh issue create before starting.

Rule 2: Branch Naming Convention

{category}/{issue-number}-{short-description}

Examples:

• research/42-execution-evidence-feasibility
• impl/55-evidence-grade-materializer
• infra/60-slack-bot-setup

The issue number in the branch name makes it trivial to check if someone else is working on the same thing (git branch -r | grep /42-).

Rule 3: Daily Slack Digest (Automated)

A GitHub Action runs daily and posts to the team Slack channel:

• Issues moved to "In Progress" today
• PRs opened today
• PRs merged today
• Issues with no activity for >3 days (stale alert)

This replaces standups. The developer doesn't need to actively communicate — the bot surfaces their activity.

---

Slack Channel Structure

One channel: #sv0-dev

Keep it simple. A 3-person team does not need channel proliferation.

Slack is a notification pipe, not a system of record. No tasks live in Slack. All tasks are GitHub Issues. Slack's free tier has 90-day message history — this is fine because every notification originates from a GitHub Issue or PR with permanent history. If a decision comes out of a Slack conversation, capture it as a comment on the relevant GitHub Issue.

What posts to #sv0-dev:

Source	Event	Format
GitHub Actions	Issue assigned / moved to In Progress	:construction: @lucky claimed #42 — execution evidence feasibility
GitHub Actions	PR opened	:rocket: PR #55 opened by @lucky — evidence grade materializer
GitHub Actions	PR merged	:white_check_mark: PR #55 merged — evidence grade materializer
GitHub Actions	Daily digest	Summary of open/in-progress/stale issues
Manual	Blockers, decisions, questions	Team members post directly

Claude Code Session Summaries (Automated)

A Stop hook (.claude/hooks/session-summary-to-slack.sh) runs after every Claude Code response. If commits were created in the last 10 minutes, it posts a summary to #sv0-dev via Slack webhook:

:robot_face: Claude Code session activity (sv0-platform / impl/55-evidence-grades)
• a1b2c3d Add EvidenceGrade type and computeEvidenceGrade function
• d4e5f6g Add evidence grade unit tests

Requires SLACK_WEBHOOK_URL in .claude/settings.local.json env. No commits = no post (avoids noise from research/chat sessions).

---

Implementation Steps

Step 1: Create GitHub Project (~15 min)

1. Create a GitHub Project named "SecurityV0 Roadmap" at the org level (spans sv0-platform and sv0-connectors).
2. Add three views: "Research", "Implementation", "Infrastructure" — each filtered by the corresponding label.
3. Add a "Board" view with columns: Backlog → In Progress → Review → Done.
4. Add custom field "Category" (single-select: Research / Implementation / Infrastructure).

Step 2: Migrate Current Plans to Issues (~30 min)

Convert the active items from PLAN-TRACKER.md into GitHub Issues:

Current Plan	Issue Title	Label
G1: Exposure Aggregation APIs	Implement exposure aggregation API endpoints	implementation
G2: Remediation Content Generation	Build remediation content generation	implementation
G3: Scope Drift UX	Add scope drift visualization to UI	implementation
G4: Shared Azure Modules	Extract shared Azure modules across connectors	implementation
G5: Function Key Authority Paths	Implement function key authority path resolution	implementation
G6: Pilot Readiness Checklist	Complete pilot readiness checklist	infrastructure
Evidence-Graded Authority Paths (Phase 0-5)	6 issues, one per phase	implementation

Each issue body links to the full plan document.

Step 3: Create Slack Channel + Webhook (~15 min)

1. Create #sv0-dev channel.
2. Add a Slack incoming webhook (or use the GitHub Slack integration).
3. Configure GitHub → Slack notifications for the repos: issue assignments, PR opens, PR merges.

Step 4: GitHub Action for Daily Digest (~1 session)

Create .github/workflows/daily-digest.yml in the org-level .github repo (or in sv0-platform):

name: Daily Dev Digest
on:
  schedule:
    - cron: '0 9 * * 1-5'  # 9am UTC, weekdays
  workflow_dispatch: {}

jobs:
  digest:
    runs-on: ubuntu-latest
    steps:
      - name: Collect project status
        uses: actions/github-script@v7
        with:
          script: |
            // Query GitHub Project for issues updated in last 24h
            // Format summary
            // Post to Slack via webhook

Step 5: Already Done — Claude Code Hooks

The following hooks are already created in sv0-platform/.claude/:

Hook	File	Trigger
Issue awareness	.claude/hooks/check-github-issues.sh	UserPromptSubmit — injects open issues into agent context
Slack session summary	.claude/hooks/session-summary-to-slack.sh	Stop — posts commit summary to Slack if commits exist
Agent instructions	AGENTS.md § Task Tracking	Every session — agents auto-create/claim/close issues

To activate Slack posting: Add SLACK_WEBHOOK_URL to .claude/settings.local.json:

{
  "env": {
    "SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/T.../B.../..."
  }
}

---

What Stays Where

Content	Location	Why
Product vision, specs, user stories	Notion (synced to sv0-documentation/docs/product/notion-synced/)	CEO writes here, sync keeps docs current
Research, reviews, feasibility studies	sv0-documentation/docs/product/reviews/	Long-form analysis, versioned in git
Architecture docs, ADRs	sv0-documentation/docs/architecture/	Canonical architecture reference
Implementation plans (detailed)	sv0-platform/docs/plans/ or sv0-documentation/docs/plans/	File-level change inventories
Task status, assignments, progress	GitHub Projects	Linked to PRs, automated status
Daily communication, blockers	#sv0-dev Slack channel	Low-friction, bot-augmented
Operational procedures	sv0-documentation/docs/runbooks/	This directory

---

What This Replaces

Before	After
PLAN-TRACKER.md manually updated	GitHub Project board (auto-updates from PRs)
No visibility into who's working on what	Issue assignment = claim. Slack digest = passive awareness.
Duplicate work discovered after the fact	Branch naming + issue assignment prevents overlap
Developer needs to actively communicate	Bot surfaces their GitHub activity automatically
Research and implementation mixed in one list	Three filtered views separate work categories

PLAN-TRACKER.md can remain as a read-only snapshot generated from GitHub Projects (or deprecated once the team trusts the board).

---

Cost

Item	Cost
GitHub Projects	Free (included with GitHub)
Slack channel	Free (within free tier or existing workspace)
GitHub → Slack integration	Free
GitHub Action (daily digest)	Free (within GitHub Actions minutes)
Claude Code hook	Free (local script)

Total: $0/month. All tooling is within free tiers for a 3-person team.