!/usr/bin/env python3 import os import json import hashlib from datetime import datetime from github import Github import requests

CONTEXT_DIR = "./context" GITHUB_TOKEN = os.getenv("GITHUB_TOKEN") STRIPE_API_KEY = os.getenv("STRIPE_API_KEY")

def generate_event_id(event_type: str, payload: dict) -> str: raw = f"{event_type}:{json.dumps(payload, sort_keys=True)}" return hashlib.sha256(raw.encode()).hexdigest()[:12]

def normalize_event(event_type: str, source: str, payload: dict) -> dict: return { "id": generate_event_id(event_type, payload), "type": event_type, "source": source, "timestamp": datetime.utcnow().isoformat(), "payload": payload, "status": "ingested" }

def fetch_github_prs() -> list: g = Github(GITHUB_TOKEN) repo = g.get_repo(os.getenv("REPO_NAME")) prs = repo.get_pulls(state="open") return [normalize_event("github.pr", "github", {"number": pr.number, "title": pr.title, "url": pr.html_url}) for pr in prs]

def fetch_stripe_events() -> list: url = "https://api.stripe.com/v1/events" headers = {"Authorization": f"Bearer {STRIPE_API_KEY}"} resp = requests.get(url, headers=headers, params={"limit": 10}) events = resp.json().get("data", []) return [normalize_event("stripe.event", "stripe", {"type": e["type"], "id": e["id"]}) for e in events]

def main(): os.makedirs(CONTEXT_DIR, exist_ok=True) all_events = fetch_github_prs() + fetch_stripe_events()

for event in all_events:
    path = os.path.join(CONTEXT_DIR, f"{event['id']}.json")
    if not os.path.exists(path):
        with open(path, "w") as f:
            json.dump(event, f, indent=2)
print(f"[{datetime.utcnow().isoformat()}] Ingested {len(all_events)} events.")

if name == "main": main()

#### Taskfile.yml (Execution Engine)
Standardizes routine operations with dependency ordering and environment validation.

```yaml
version: '3'

vars:
  APP_DIR: ./app
  ENV_FILE: .env.production

tasks:
  validate:
    desc: Validate environment and dependencies
    cmds:
      - test -f {{.ENV_FILE}} || (echo "Missing .env.production" && exit 1)
      - docker compose --project-directory {{.APP_DIR}} config --quiet
    silent: true

  deploy:
    desc: Deploy application to production
    deps: [validate]
    cmds:
      - docker compose --project-directory {{.APP_DIR}} build --no-cache
      - docker compose --project-directory {{.APP_DIR}} up -d --remove-orphans
      - task: healthcheck
    env:
      DEPLOY_ENV: production

  healthcheck:
    desc: Verify deployment health
    cmds:
      - curl -sf http://localhost:8080/health || (echo "Healthcheck failed" && exit 1)
    silent: true

  sync-context:
    desc: Run daily context ingestion
    cmds:
      - python3 scripts/sync_context.py
    env:
      PYTHONPATH: .

GitHub Actions: Auto-Triage & Routing

Automates context routing based on event type.

name: Context Router
on:
  issues:
    types: [opened, labeled]
  pull_request:
    types: [opened, ready_for_review]

jobs:
  route-context:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Extract Event Metadata
        id: meta
        run: |
          echo "type=${{ github.event_name }}" >> $GITHUB_OUTPUT
          echo "action=${{ github.event.action }}" >> $GITHUB_OUTPUT
          echo "title=${{ github.event.issue.title || github.event.pull_request.title }}" >> $GITHUB_OUTPUT

      - name: Write Context Record
        run: |
          mkdir -p context
          cat > "context/${{ github.run_id }}.json" << EOF
          {
            "id": "${{ github.run_id }}",
            "type": "${{ steps.meta.outputs.type }}",
            "action": "${{ steps.meta.outputs.action }}",
            "title": "${{ steps.meta.outputs.title }}",
            "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
            "status": "routed"
          }
          EOF

      - name: Commit Context Fabric
        run: |
          git config user.name "context-router[bot]"
          git config user.email "bot@codcompass.dev"
          git add context/
          git diff --staged --quiet || git commit -m "chore: ingest context ${{ github.run_id }}"
          git push

Pitfall Guide

1. Automating Broken Workflows Automation amplifies existing processes. If your intake routing is inconsistent, automating it will generate noise at scale. Validate the manual flow first, then codify it.

2. Over-Engineering the Context Layer Building a custom database, search index, or real-time sync server introduces maintenance overhead. Start with Git + JSON/Markdown + cron/webhooks. Scale complexity only when query latency or storage constraints demand it.

3. Ignoring Idempotency in Automation Webhooks retry, APIs throttle, and cron jobs overlap. Without deterministic IDs and duplicate detection, your context fabric will fracture. Always hash payloads and check existence before ingestion.

4. Treating Productivity as a Static Configuration Systems decay as product scope, team size, and tooling evolve. Schedule weekly system reviews to prune unused automations, update routing rules, and adjust task dependencies.

5. Neglecting Async Communication Boundaries Push notifications create interrupt-driven workflows. Convert real-time alerts to digest formats (daily email, Slack summary, or context fabric updates). Preserve deep work blocks by batching communication.

6. Conflating Tool Count with System Capability Adding more tools increases integration surface area and context fragmentation. Prefer unified platforms or API-driven consolidation. Every new tool must justify its existence by reducing switch latency or automating a manual step.

7. Skipping Observability & Rollback Paths Automation failures are inevitable. Without logging, alerting, and manual override capabilities, a failed deploy or misrouted ticket can cascade. Implement circuit breakers, dry-run modes, and explicit rollback commands in your task runner.

Production Bundle

Action Checklist

• Audit current toolchain and map context flow gaps
• Initialize local context fabric repository with JSON/Markdown schema
• Implement idempotent ingestion script for primary services (GitHub, Stripe, hosting)
• Codify all routine operations in a declarative task runner (Taskfile/Make)
• Configure GitHub Actions for automated context routing and commit sync
• Establish weekly system review cadence (metrics, pruning, configuration updates)
• Implement async communication boundaries (digests over push notifications)
• Add observability layer (CSV/JSON metrics, simple dashboard, rollback procedures)

Decision Matrix

Configuration Template

Copy-paste ready structure for immediate deployment:

solo-productivity-system/
├── context/                 # Local context fabric
│   └── .gitkeep
├── scripts/
│   ├── sync_context.py      # Ingestion engine
│   └── metrics_collector.py # Observability loop
├── Taskfile.yml             # Execution engine
├── .github/
│   └── workflows/
│       └── context-router.yml
├── .env.example             # Secret management template
└── README.md                # System runbook

.env.example:

GITHUB_TOKEN=ghp_xxxxxxxxxxxx
STRIPE_API_KEY=sk_live_xxxxxxxxxxxx
REPO_NAME=owner/repo
CONTEXT_DIR=./context
SYNC_INTERVAL=3600

Taskfile.yml (production variant):

version: '3'

tasks:
  init:
    desc: Initialize context fabric and validate environment
    cmds:
      - mkdir -p context
      - cp .env.example .env
      - task: validate

  validate:
    desc: Check required variables and dependencies
    cmds:
      - test -n "$GITHUB_TOKEN" || (echo "Missing GITHUB_TOKEN" && exit 1)
      - test -n "$STRIPE_API_KEY" || (echo "Missing STRIPE_API_KEY" && exit 1)
      - python3 -c "import requests, github" || pip install -r requirements.txt
    silent: true

  ingest:
    desc: Run daily context synchronization
    cmds:
      - python3 scripts/sync_context.py
    env:
      PYTHONPATH: .

  deploy:
    desc: Production deployment with health verification
    deps: [validate]
    cmds:
      - docker compose build --no-cache
      - docker compose up -d --remove-orphans
      - curl -sf http://localhost:8080/health || (echo "Deploy failed" && docker compose down && exit 1)

Quick Start Guide

1. Initialize the Fabric: Clone the template repository, copy .env.example to .env, and populate API keys. Run task init to validate environment and create the context directory.
2. Deploy Ingestion & Routing: Commit the scripts/sync_context.py and .github/workflows/context-router.yml files. Push to trigger the GitHub Action. Verify context records appear in context/ after the first run.
3. Codify Execution: Replace ad-hoc terminal commands with Taskfile.yml tasks. Run task validate and task deploy to confirm deterministic behavior. Integrate task runner into your CI/CD pipeline.
4. Close the Loop: Schedule a weekly 30-minute review. Export context/ metrics, analyze switch frequency and automation success rates, and prune unused routing rules. Adjust sync intervals and digest formats based on observed cognitive load.

This system transforms productivity from a behavioral goal into an engineered pipeline. By centralizing context, automating intake, standardizing execution, and enforcing observability, solo founders eliminate context-switching tax and reclaim sustainable delivery velocity.