Skip to content

workflows.md

Latest commit

 

History

History
448 lines (306 loc) · 9.09 KB

workflows.md

File metadata and controls

448 lines (306 loc) · 9.09 KB
Raw

Common Workflows

Step-by-step guides for the tasks you will perform most often with POS.

Adding a New Context

A context represents a distinct area of work: a job, side project, freelance client, or personal goal.

Steps

  1. Edit pos.yaml -- Add a new entry under contexts::
contexts:
  # ... existing contexts ...

  - id: freelance-acme
    type: "moonlight"
    name: "Freelance - Acme Corp"
    role: "Consultant"
    focus: "API migration from v1 to v2"
    stack: "go"
    shortcuts: ["@acme"]
    path: "contexts/freelance-acme"
  1. Create the directory structure:
mkdir -p contexts/freelance-acme/projects
mkdir -p contexts/freelance-acme/plans
mkdir -p contexts/freelance-acme/docs
  1. Create the status file at contexts/freelance-acme/status.yaml:
context: "freelance-acme"
last_updated: "2026-03-19T10:00:00Z"

session:
  active: false
  started: null
  ended: null
  task: null
  notes: []

current_task: null
completed_today: []
pending_review: []
blockers: []
  1. Create the QUICK-START.md at contexts/freelance-acme/QUICK-START.md:
# freelance-acme -- Quick Start

## What This Is
API migration consulting for Acme Corp. Migrating REST API from v1 to v2.

## Current Focus
Phase 1: Audit existing v1 endpoints and document breaking changes.

## Key Files
- contexts/freelance-acme/projects/acme-api/ -- Main repository
- contexts/freelance-acme/plans/ -- Sprint plans

## Stack
Go 1.22, PostgreSQL, gRPC
  1. Regenerate docs:
./scripts/pos-generate.sh
  1. Sync state:
./scripts/sync-state.sh

Starting a Work Session

With Claude Code

Claude Code registers sessions automatically via hooks. Just open it in the repo and start working:

/session start freelance-acme

With Any Other Tool

Register via script:

./scripts/session-register.sh "cursor" "freelance-acme" "standard"

Then tell the tool to read context:

Read contexts/freelance-acme/QUICK-START.md for current context.
Read .state/snapshot.yaml for system state.

Verify Your Session Is Registered

ls .handoff/sessions/

You should see your session file (e.g., cursor.yaml).

Switching Contexts

Switching contexts means closing your current session and opening a new one in a different context.

Steps

  1. Close the current session:
./scripts/session-close.sh "cursor" "Completed endpoint audit for v1 API"
  1. Register a new session in the target context:
./scripts/session-register.sh "cursor" "dayjob" "standard"
  1. Load the new context:
Read contexts/dayjob/QUICK-START.md
Read contexts/dayjob/status.yaml
  1. Check for pending handoffs in the new context:
ls .handoff/handoffs/ | grep dayjob

Read the most recent handoff to see where work left off.

Creating and Approving a Plan

POS optionally enforces a Plan-Approve-Execute workflow. Code edits are blocked until a plan is approved.

Step 1: Create the Plan

Create a plan file in the context plans directory:

mkdir -p contexts/dayjob/plans/sprints

Write the plan at contexts/dayjob/plans/sprints/sprint-1-auth.yaml:

sprint: 1
name: "User Authentication"
context: dayjob
status: pending

goal: |
  Implement OAuth2 login flow with Google and GitHub providers.

phases:
  - name: "Backend Auth"
    tasks:
      - "Set up OAuth2 provider configuration"
      - "Implement callback handlers"
      - "Add session management"
    acceptance: "Users can log in via Google or GitHub"

  - name: "Frontend Integration"
    tasks:
      - "Add login buttons to landing page"
      - "Implement auth state management"
      - "Add protected route wrapper"
    acceptance: "Login flow works end-to-end in browser"

blockers: []
dependencies: []

Step 2: Approve the Plan

./scripts/approve-plan.sh contexts/dayjob/plans/sprints/sprint-1-auth.yaml

Output:

Plan approved and code edits unlocked for context: dayjob
  Plan: contexts/dayjob/plans/sprints/sprint-1-auth.yaml
  Lock: .claude/.plan-lock-dayjob

Step 3: Implement

Code edits under contexts/dayjob/projects/ are now allowed. The lock file is automatically removed when the session closes.

Handing Off Between Sessions

Handoffs preserve state between AI sessions so work carries over without loss.

Closing a Session With a Good Handoff

When closing a session, provide a detailed summary:

./scripts/session-close.sh "claude-code" "Implemented OAuth callback handlers for Google and GitHub. Backend auth is complete. Frontend integration not started."

For a richer handoff, edit the handoff file after creation to fill in the structured fields:

# Find the handoff file
ls .handoff/handoffs/ | tail -1

Edit it to add:

completed:
  - "OAuth2 provider configuration"
  - "Google callback handler"
  - "GitHub callback handler"
  - "Session management with JWT"
pending:
  - "Frontend login buttons"
  - "Auth state management"
  - "Protected route wrapper"
blockers: []
resume_point: |
  Backend auth is complete and tested. Start frontend integration.
  Key file: contexts/dayjob/projects/my-api/src/auth/oauth.ts
  Branch: feature/auth
files_modified:
  - "contexts/dayjob/projects/my-api/src/auth/oauth.ts"
  - "contexts/dayjob/projects/my-api/src/auth/session.ts"
  - "contexts/dayjob/projects/my-api/tests/auth.test.ts"

Resuming From a Handoff

In your next session, read the latest handoff:

ls .handoff/handoffs/ | sort | tail -1

Then tell your AI tool:

Read .handoff/handoffs/2026-03-19-claude-code.yaml to understand where the last session left off. Resume from the resume_point.

Handing Off Between Different AI Tools

POS is designed for work to flow between different tools. A common pattern:

  1. Claude Code (reasoning) creates an architecture plan
  2. Cursor (standard) implements the plan
  3. Claude Code (reasoning) reviews the implementation

Steps

Session 1 -- Claude Code creates the plan:

./scripts/session-register.sh "claude-opus" "dayjob" "reasoning"
# ... creates plan, approves it ...
./scripts/session-close.sh "claude-opus" "Created auth architecture plan. Ready for implementation."

Session 2 -- Cursor implements:

./scripts/session-register.sh "cursor" "dayjob" "standard"

Tell Cursor:

Read .handoff/handoffs/2026-03-19-claude-opus.yaml for context.
Read the plan file referenced in the handoff.
Implement the plan.

When done:

./scripts/session-close.sh "cursor" "Implemented auth per architecture plan. Ready for review."

Session 3 -- Claude Code reviews:

./scripts/session-register.sh "claude-opus" "dayjob" "reasoning"
Read .handoff/handoffs/2026-03-19-cursor.yaml to see what was implemented.
Review the changes.

Running a Health Check

Health checks verify that a context is in good shape.

./scripts/check-health.sh dayjob

Output:

Checking health for context: dayjob
OK: Status file size (2KB)
OK: Project Indices
OK: Skill validation
OK: Skill templates up to date
System Health: GOOD

If issues are found:

WARN: Status file is bloated (15KB > 10KB). Run: ./scripts/archive-status.sh dayjob
WARN: Skill validation found issues. Run: ./scripts/validate-skills.sh
WARN: Skill templates are stale. Run: ./scripts/generate-skills.sh

Follow the suggested commands to fix each issue.

Archiving Stale Data

Over time, status.yaml files accumulate completed_today entries and grow large. Archive them periodically.

Archive Completed Items

./scripts/archive-status.sh dayjob

This moves completed items from contexts/dayjob/status.yaml to contexts/dayjob/logs/status-archive-2026-03.yaml and clears the completed_today list.

Archive Skill Artifacts

When a feature branch is merged, archive its artifacts:

source scripts/lib-artifacts.sh
artifact_archive "dayjob" "feature/auth"

Clean Up Old Artifacts

Remove archived artifacts older than 30 days:

source scripts/lib-artifacts.sh
artifact_cleanup 30

Checking the Task Queue

The task queue shows what work is available for AI models to claim.

View the Queue

cat .handoff/queue.yaml

Refresh the Queue

./scripts/sync-queue.sh

Claim a Task

./scripts/task-start.sh DAYJOB-RESUME dayjob claude-code

Complete a Task

./scripts/task-complete.sh 2026-03-19-dayjob-claude-code-DAYJOB-RESUME "Finished the auth implementation"

Setting Up Daily Automation

Run state and queue sync automatically each day.

Using Cron

crontab -e

Add:

0 22 * * * /absolute/path/to/repo/scripts/daily-sync.sh

This runs sync-state.sh and sync-queue.sh at 22:00 UTC daily and logs the result to .state/sync.log.

Further Reading