workstream-cli 0.0.1__py3-none-any.whl

workstream/repo_discovery.py

@@ -0,0 +1,158 @@
+"""Scan directories for git repos and build a markdown index of activity."""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+from workstream.git import branch_ahead_count, list_branches, recent_commits
+
+
+def discover_repos(repo_dirs: list[str]) -> list[Path]:
+    """Find git repositories in the given directories.
+
+    For each directory, checks if the directory itself is a repo and scans
+    its immediate subdirectories for ``.git/`` directories. Silently skips
+    dirs that don't exist.
+    """
+    repos: set[Path] = set()
+    for raw in repo_dirs:
+        parent = Path(raw).expanduser().resolve()
+        if not parent.is_dir():
+            continue
+        # Check the directory itself
+        if (parent / ".git").is_dir():
+            repos.add(parent)
+        # Check immediate children
+        try:
+            for child in parent.iterdir():
+                if child.is_dir() and (child / ".git").is_dir():
+                    repos.add(child)
+        except PermissionError:
+            continue
+    return sorted(repos)
+
+
+def find_duplicate_repo_names(repo_dirs: list[str]) -> dict[str, list[Path]]:
+    """Find repo names that appear in multiple parent directories.
+
+    Returns {name: [path1, path2, ...]} for names with >1 occurrence.
+    """
+    from collections import defaultdict
+    by_name: defaultdict[str, list[Path]] = defaultdict(list)
+    for repo_path in discover_repos(repo_dirs):
+        by_name[repo_path.name].append(repo_path)
+    return {name: paths for name, paths in by_name.items() if len(paths) > 1}
+
+
+def _default_branch(branches: list[str]) -> str | None:
+    """Pick the default branch: main > master > first available."""
+    if not branches:
+        return None
+    if "main" in branches:
+        return "main"
+    if "master" in branches:
+        return "master"
+    return branches[0]
+
+
+def _repo_summary(repo: Path, cutoff: str) -> dict | None:
+    """Gather activity data for a single repo. Returns None on failure."""
+    try:
+        branches = list_branches(repo)
+    except Exception:
+        return None
+
+    default = _default_branch(branches)
+    if default is None:
+        return None
+
+    try:
+        default_commits = recent_commits(repo, cutoff, default)
+    except Exception:
+        default_commits = []
+
+    active_branches: list[dict] = []
+    for branch in branches:
+        if branch == default:
+            continue
+        try:
+            commits = recent_commits(repo, cutoff, branch)
+        except Exception:
+            continue
+        if not commits:
+            continue
+        try:
+            ahead = branch_ahead_count(repo, branch)
+        except Exception:
+            ahead = 0
+        latest = commits[0]
+        active_branches.append({
+            "name": branch,
+            "ahead": ahead,
+            "date": latest["date"],
+            "subject": latest["subject"],
+        })
+
+    last_default_date = default_commits[0]["date"] if default_commits else None
+    is_active = bool(default_commits or active_branches)
+
+    return {
+        "name": repo.name,
+        "path": str(repo),
+        "default_branch": default,
+        "last_default_date": last_default_date,
+        "active_branches": active_branches,
+        "is_active": is_active,
+    }
+
+
+def build_repo_index(repos: list[Path], cutoff_date: date) -> str:
+    """Build a markdown summary of repo activity since *cutoff_date*.
+
+    Repos are split into active (any commits since cutoff) and stale.
+    Git errors on individual repos are caught and the repo is skipped.
+    """
+    if not repos:
+        return ""
+
+    cutoff = cutoff_date.isoformat()
+    summaries: list[dict] = []
+    for repo in repos:
+        info = _repo_summary(repo, cutoff)
+        if info is not None:
+            summaries.append(info)
+
+    active = [s for s in summaries if s["is_active"]]
+    stale = [s for s in summaries if not s["is_active"]]
+
+    # Derive dir list from common parents for the header
+    parents = sorted({str(Path(s["path"]).parent) for s in summaries})
+    dir_list = ", ".join(parents) if parents else "unknown"
+
+    lines: list[str] = [
+        f"### Repo index ({len(summaries)} repos from {dir_list})",
+    ]
+
+    if active:
+        lines.append("Active repos (commits within lookback period):")
+        lines.append("")
+        for info in active:
+            lines.append(f"#### {info['name']} ({info['path']})")
+            if info["last_default_date"]:
+                lines.append(f"Last default-branch commit: {info['last_default_date']}")
+            if info["active_branches"]:
+                lines.append("Branches with recent activity:")
+                for b in info["active_branches"]:
+                    lines.append(
+                        f"- {b['name']} (+{b['ahead']} ahead)"
+                        f' — {b["date"]}: "{b["subject"]}"'
+                    )
+            lines.append("")
+
+    if stale:
+        lines.append("Stale repos (no commits within lookback period):")
+        lines.append(f"- {', '.join(s['name'] for s in stale)}")
+        lines.append("")
+
+    return "\n".join(lines)

workstream/review_artifact.py

@@ -0,0 +1,96 @@
+"""Read and write review artifacts at _Workstreams/reviews/YYYY-MM-DD.md.
+
+Review artifacts record the output of each review session: focus items,
+decisions made, and freeform notes.  The frontmatter contains structured
+data (date, type, focus list); the body is freeform markdown.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+
+from workstream.markdown import parse_frontmatter, write_frontmatter
+
+
+# ── Data types ──────────────────────────────────────────────────────
+
+
+class ReviewArtifact:
+    """A single review artifact parsed from disk."""
+
+    __slots__ = ('date', 'type', 'focus', 'body', 'source_path')
+
+    def __init__(
+        self,
+        *,
+        review_date: str = '',
+        review_type: str = 'review',
+        focus: list[str] | None = None,
+        body: str = '',
+        source_path: Path | None = None,
+    ):
+        self.date = review_date or date.today().isoformat()
+        self.type = review_type
+        self.focus = focus or []
+        self.body = body
+        self.source_path = source_path
+
+    def frontmatter_dict(self) -> dict:
+        d: dict = {
+            'date': self.date,
+            'type': self.type,
+        }
+        if self.focus:
+            d['focus'] = self.focus
+        return d
+
+
+# ── I/O ──────────────────────────────────────────────────────────────
+
+
+def reviews_dir(ws_dir: Path) -> Path:
+    """Return the reviews directory, creating it if needed."""
+    d = ws_dir / 'reviews'
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def load_review(path: Path) -> ReviewArtifact:
+    """Load a review artifact from a markdown file."""
+    text = path.read_text(encoding='utf-8')
+    meta, body = parse_frontmatter(text)
+    return ReviewArtifact(
+        review_date=str(meta.get('date', '')),
+        review_type=meta.get('type', 'review'),
+        focus=meta.get('focus', []),
+        body=body.strip(),
+        source_path=path,
+    )
+
+
+def save_review(artifact: ReviewArtifact, ws_dir: Path) -> Path:
+    """Write a review artifact to _Workstreams/reviews/YYYY-MM-DD.md.
+
+    Returns the path written.
+    """
+    rdir = reviews_dir(ws_dir)
+    path = rdir / f'{artifact.date}.md'
+    meta = artifact.frontmatter_dict()
+    text = write_frontmatter(meta, artifact.body)
+    text = text.rstrip('\n') + '\n'
+    path.write_text(text, encoding='utf-8')
+    artifact.source_path = path
+    return path
+
+
+def load_latest_review(ws_dir: Path) -> ReviewArtifact | None:
+    """Load the most recent review artifact, or None if none exist."""
+    rdir = ws_dir / 'reviews'
+    if not rdir.is_dir():
+        return None
+    files = sorted(rdir.glob('*.md'), reverse=True)
+    if not files:
+        return None
+    return load_review(files[0])

workstream/scripts/migrate_statuses.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""One-time migration: tabled→snoozed, idea→Ideas entries, frontmatter cleanup, seed log.
+
+Usage:
+    python3 src/workstream/scripts/migrate_statuses.py [--dry-run]
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import date
+from pathlib import Path
+
+# Ensure src/ is importable
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from workstream.config import load_config
+from workstream.markdown import (
+    append_idea,
+    append_log_entry,
+    load_workstream,
+    parse_frontmatter,
+    write_frontmatter,
+)
+from workstream.models import IdeaEntry, LogEntry
+
+
+def migrate(dry_run: bool = False) -> None:
+    config = load_config()
+    ws_dir = config.workstreams_path
+
+    if not ws_dir.exists():
+        print(f'Workstreams directory not found: {ws_dir}')
+        return
+
+    today = date.today().isoformat()
+    files = sorted(ws_dir.glob('*.md'))
+    skip_files = {'index.md', 'inbox.md', 'dashboard.html'}
+
+    migrated = 0
+    ideas_migrated = 0
+    logs_seeded = 0
+
+    for f in files:
+        if f.name in skip_files:
+            continue
+
+        text = f.read_text(encoding='utf-8')
+        meta, body = parse_frontmatter(text)
+        if not meta:
+            continue
+
+        changed = False
+        status = meta.get('status', '')
+
+        # 1. tabled → snoozed
+        if status == 'tabled':
+            if dry_run:
+                print(f'  [DRY] Would change {f.name}: tabled → snoozed')
+            meta['status'] = 'snoozed'
+            tabled_note = meta.pop('tabled_note', '')
+            if tabled_note:
+                meta['snooze_reason'] = tabled_note
+            changed = True
+            migrated += 1
+
+        # 2. idea workstreams → for now just change to active
+        #    (In full deployment, these would become Ideas entries on parents)
+        elif status == 'idea':
+            if dry_run:
+                print(f'  [DRY] Would change {f.name}: idea → active')
+            meta['status'] = 'active'
+            changed = True
+            migrated += 1
+
+        # 3. Frontmatter cleanup: remove tabled_note if present
+        if 'tabled_note' in meta:
+            old_note = meta.pop('tabled_note')
+            if old_note and 'snooze_reason' not in meta:
+                meta['snooze_reason'] = old_note
+            changed = True
+
+        # 4. Seed initial log entry if no ## Log section exists
+        from workstream.markdown import parse_log as _parse_log
+        if not _parse_log(body):
+            created_date = str(meta.get('created', today))
+            log_detail = f"({meta.get('status', 'active')}, {meta.get('size', 'day')})"
+            entry = LogEntry(date=created_date, event='created', detail=log_detail)
+            body = append_log_entry(body, entry)
+
+            # If currently snoozed (either from migration or already), add snoozed log
+            if meta.get('status') == 'snoozed':
+                reason = meta.get('snooze_reason', '')
+                until = meta.get('snooze_until', '')
+                if until:
+                    detail = f'until {until}: {reason}' if reason else f'until {until}'
+                else:
+                    detail = f'indefinitely: {reason}' if reason else 'indefinitely'
+                body = append_log_entry(body, LogEntry(date=today, event='snoozed', detail=detail))
+
+            changed = True
+            logs_seeded += 1
+            if dry_run:
+                print(f'  [DRY] Would seed log entry for {f.name}')
+
+        if changed and not dry_run:
+            out = write_frontmatter(meta, body)
+            out = out.rstrip('\n') + '\n'
+            f.write_text(out, encoding='utf-8')
+            print(f'  Migrated: {f.name}')
+
+    print(f'\nMigration {"(dry run) " if dry_run else ""}complete:')
+    print(f'  {migrated} status changes')
+    print(f'  {ideas_migrated} ideas migrated')
+    print(f'  {logs_seeded} log entries seeded')
+
+
+if __name__ == '__main__':
+    dry = '--dry-run' in sys.argv
+    migrate(dry_run=dry)

workstream/skills/workstream_context/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: workstream-context
+description: General workstream context — command reference, file structure, offline instructions
+author: Mahmoud Hashemi
+version: 2026-04-02.1
+---
+
+# Workstream Context
+
+Workstream is an attention management system for trains of thought that span projects and time. It is not project management. A workstream is a persistent train of thought — a problem, initiative, or area of concern that you return to across sessions, days, and weeks.
+
+## File Structure
+
+All workstream data lives under a `_Workstreams/` directory:
+
+| Path | Purpose |
+|------|---------|
+| `_Workstreams/*.md` | One markdown file per workstream |
+| `_Workstreams/reviews/` | Review artifacts, named `YYYY-MM-DD.md` |
+| `_Workstreams/focus/` | Focus artifacts (weekly priorities) |
+| `_Workstreams/inbox.md` | Unmatched thoughts not yet assigned to a workstream |
+| `config.yaml` | Configuration in `~/.config/workstream/` or `_Workstreams/config.yaml` |
+
+## Workstream File Frontmatter
+
+Each workstream markdown file has YAML frontmatter with these fields:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique identifier (slug) |
+| `title` | Human-readable title |
+| `status` | One of: `active`, `snoozed`, `blocked`, `completed`, `dropped` |
+| `size` | Effort estimate: `hour`, `day`, `week`, or `open` |
+| `tags` | List of categorization tags |
+| `repos` | Associated repository paths |
+| `parent` | Parent workstream id (for nesting) |
+| `summary` | Brief description of current state |
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `ws list [--active\|--all\|--search\|--paths]` | List workstreams |
+| `ws show <id>` | Detail view of a single workstream |
+| `ws next [--quick\|--tag\|--size\|--focus]` | Suggest what to work on next |
+| `ws new <title>` | Create a new workstream |
+| `ws stale [--days N]` | Find neglected workstreams |
+| `ws snooze <id> [reason]` | Defer a workstream |
+| `ws wake <id>` | Resume a snoozed workstream |
+| `ws block <id> <reason>` | Mark a workstream as blocked on an external dependency |
+| `ws unblock <id>` | Clear a blocked status |
+| `ws update-status <id> <status> [reason]` | Transition workstream status |
+| `ws idea <parent-id> <text>` | Add an idea to a workstream |
+| `ws ideas` | List ideas across workstreams |
+| `ws promote <parent> <idx>` | Promote an idea to a workstream |
+| `ws checkin` | Daily check-in across active workstreams |
+| `ws sweep [--discover]` | Scan repos for plan/branch updates |
+| `ws review` | Structured multi-workstream review session |
+| `ws focus` | Set weekly priorities |
+| `ws report [--since Nd]` | Activity summary over a time range |
+| `ws index` | Regenerate the workstream index |
+| `ws tree` | Display workstream hierarchy |
+| `ws nest <child> <parent>` | Place a workstream under a parent |
+| `ws unnest <id>` | Remove a workstream from its parent |
+| `ws resume <id>` | Context resumption briefing for a workstream |
+
+## If ws Is Not Installed
+
+You can work with workstreams directly through the filesystem:
+
+- Workstream files live in `_Workstreams/` as plain markdown.
+- Status is stored in YAML frontmatter at the top of each file.
+- The `## Next` section contains pending actions for the workstream.
+- The `## Thread` section contains dated journal entries tracking progress.
+- To update a workstream, edit the file directly: change frontmatter fields, add entries to the thread, or update the next-actions list.

workstream/skills/workstream_focus/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: workstream-focus
+description: Prospective focus session — set priorities and identify blocked/agent-actionable items
+author: Mahmoud Hashemi
+version: 2026-04-02.1
+date: 2026-04-01
+---
+
+# Workstream Focus
+
+You are a prospective planning partner helping set focus and priorities for workstreams. Unlike review (retrospective cleanup), focus is forward-looking: what matters this week, what's blocked, what can be delegated to an agent.
+
+## Context
+
+The user manages multiple workstreams (trains of thought spanning projects and time) tracked as markdown files in a `_Workstreams/` directory. Focus sessions produce focus docs that feed `ws next` with structured priorities. Focus docs live at `_Workstreams/focus/YYYY-MM-DD.md`.
+
+**Review vs Focus:** Review is retrospective — what happened, what to snooze/drop/wake. Focus is prospective — what matters now, what's blocked, what can be delegated. Review looks back to clean up. Focus looks forward to commit.
+
+## Iteration vs New Mode
+
+A focus session operates in one of two modes, determined by whether a current focus doc exists.
+
+**Iteration mode** (existing focus doc this week): Shorter session. The existing focus doc is loaded as context. Surface what shifted since it was written. Ask what changed — new blockers, resolved items, priority shifts. Quick update, not a full walkthrough.
+
+**New mode** (no focus doc this week, or `--new` flag): Full walkthrough from scratch. If a previous focus doc exists (from last week), it's offered for continuity context — check which priorities got attention, which carried over, which evaporated.
+
+## Focus Session Protocol
+
+When the focus manifest is present, follow this protocol step by step.
+
+### 1. Orient
+
+Surface current state from the manifest:
+
+- Active count, blocked count, stale count, expiring snoozes
+- If iterating: load existing focus doc, note what's changed since it was written
+- If previous focus exists (from last week): check which priorities got attention and which didn't
+
+> "You have N active workstreams, N blocked, N stale. Your last focus set priorities X, Y, Z — here's what moved."
+
+### 2. What's top of mind?
+
+Open-ended intake. Let the user lead:
+
+- "What's most important this week?"
+- "Any deadlines or external pressures?"
+- "Anything keeping you up at night?"
+
+Don't rush this. The answer often reveals priorities the workstream list doesn't capture.
+
+### 3. Map to workstreams
+
+Connect stated priorities to the workstream graph:
+
+- Associate each stated priority with an existing workstream
+- If something doesn't match an existing workstream, offer to create one with `ws new`
+- Rank by impact: what has the highest positive impact if done? What has the highest negative impact if dropped?
+- Aim for 2–3 priorities. More than 5 is not focus — it's a to-do list.
+- Workstreams with no next actions and all plans terminal (implemented/obsolete) may be completion candidates — suggest `ws update-status <id> completed` after capturing follow-up ideas.
+
+### 4. Identify blocked
+
+Surface workstreams that are stuck:
+
+- Which workstreams are waiting on something external?
+- What specifically is blocking them?
+- Offer to set blocked status: `ws block <id> <reason>`
+- Distinguish clearly: is this truly blocked (external dependency, waiting on another person, missing access) or just deprioritized? Deprioritized items are not blocked — they're choices.
+
+### 5. Identify agent-actionable
+
+Surface workstreams an agent could advance without the user:
+
+- No plans → obvious first action is a `/plan` session
+- Clear `next_actions` with no ambiguity → could potentially delegate
+- Research tasks, boilerplate, mechanical refactors → good candidates
+- Infer from workstream state, but confirm with the user — only they know the full context
+
+### 6. Capture
+
+Write or update the focus doc at `_Workstreams/focus/YYYY-MM-DD.md`.
+
+Frontmatter structure:
+
+```yaml
+---
+date: YYYY-MM-DD
+type: focus
+expires: YYYY-MM-DD  # end of calendar week
+supersedes: YYYY-MM-DD  # optional, date of previous focus doc
+priorities:
+  - id: <ws-id>
+    reason: "Why this matters"
+  - id: <ws-id>
+    reason: "Why this matters"
+blocked:
+  - id: <ws-id>
+    on: "What's blocking it"
+agent_actionable:
+  - id: <ws-id>
+    action: "What an agent could do"
+context: "External context (deadlines, events, etc.)"
+---
+
+## Focus
+
+<Summary of decisions and rationale from the conversation>
+```
+
+If iterating on an existing doc, preserve decisions that haven't changed. Update what shifted. Note in the body what changed and why.
+
+## Available Tools
+
+- `ws list` — see all workstreams (use --active, --all, --tag, --search, --paths flags)
+  - `ws list --search <substring>` — filter workstreams by title/repo/tag substring (implies --all)
+  - `ws list --paths` — include workstream file path and repo directory paths in output
+- `ws show <id>` — deep-dive into a specific workstream
+- `ws next [--tag X] [--size X]` — suggest what to work on next
+- `ws stale [--days N]` — find neglected workstreams
+- `ws new <title>` — create a new workstream (defaults to active)
+- `ws snooze <id> [reason]` — set a workstream aside with optional reason
+- `ws wake <id>` — bring a snoozed workstream back to active
+- `ws block <id> <reason>` — mark a workstream as blocked with reason
+- `ws unblock <id>` — remove blocked status from a workstream
+- `ws focus` — start or iterate on a focus session
+- `ws idea <parent-id> <text>` — capture an idea on a parent workstream
+- `ws checkin` — quick daily check-in
+- `ws sweep` — scan repos for plan/branch updates
+- `ws report [--since Nd]` — summarize recent activity
+- `ws tree` — show workstream hierarchy as an ASCII tree
+- `ws update-status <id> <status> [reason]` — transition to any status (completing, dropping, reopening)
+
+## Principles
+
+- This is about choosing where to spend time, not completing everything.
+- Fewer priorities = better. 2–3 is ideal. More than 5 is not focus.
+- Be direct about what's being neglected. Choosing means not-choosing.
+- Respect the user's autonomy — suggest, don't dictate.
+- Blocked means truly stuck on an external dependency, not just deprioritized.
+- Agent-actionable is contextual — infer from workstream state, confirm with the user.
+- A focus doc that doesn't change behavior is theater. Push for concrete commitments.

workstream/skills/workstream_init/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: workstream-init
+description: Interactive workstream discovery from sprint notes and repos — cold-start bootstrapping
+author: Mahmoud Hashemi
+version: 2026-04-02.1
+---
+
+# Workstream Init
+
+You are helping the user discover and create workstreams from their existing sprint notes.
+This is a bootstrapping conversation — the user may have zero or few workstreams and wants to
+populate their workstream tree from recent notes.
+
+## Context
+
+The user's system prompt contains a **Bootstrap Context** section with:
+- Today's date and the lookback period
+- A list of recent sprint files (with dates and sizes)
+- A **repo index** showing git repos, branches, and recent commits (if repo dirs are configured)
+- The current workstream tree (may be empty)
+
+The sprint files are in the notes directory and you can read them with your file tools.
+
+### Repo Context
+
+If the manifest includes a repo index, use it as a primary signal for workstream discovery:
+- **Active repos are strong signals for top-level workstreams.** A repo with recent commits likely represents ongoing work.
+- **Branches represent sub-workstreams or tactical work.** A feature branch like `feature/onboarding-v2` may be a sub-workstream under the repo's parent workstream.
+- **Some repos may be worktrees, forks, or draft clones of the same project** — ask before creating duplicate workstreams.
+- **Not all workstreams have repos.** Non-code workstreams (fundraising, hiring, community) come from note themes only.
+- **Cross-reference notes with repos.** A theme from sprint notes + an active repo = high-confidence workstream.
+- **Stale repos** (no recent commits) may still be relevant if they appear in notes. Ask the user.
+
+## Process
+
+### Pass 1: Interactive Theme Discovery
+
+1. **Read the newest 2-3 sprint files** to get a sense of what the user has been working on
+2. **Identify recurring themes**: projects, products, investigations, ideas, stalled work. Cross-reference with the repo index if available — active repos are strong theme signals.
+3. **Propose workstreams** in batches of 5-7 using the `ask` tool:
+   - The ask tool has a short input timeout — large lists will auto-select before the user finishes reading.
+   - Group themes by area (e.g., "Product workstreams", then "FOSS/side projects", then "Business/ops").
+   - Each batch: multi-select list. Include a note in the question: "You can add any workstreams not listed here right after selection."
+4. After the selection batches, ask: "Any workstreams I missed? Describe them and I'll create them." (free-text input, not multi-select)
+5. **Ask the user how they want to configure workstreams:**
+   - "Want to go through each workstream one at a time, or configure them all in one batch?"
+   - **One at a time (default):** For each approved theme, ask individually:
+     - Priority: **active** (working on it now), **snooze for next week** (not now, revisit soon), **snooze for next month** (revisit later)
+     - Size estimate: hour, day, week, open
+     - Tags from: #code, #business, #fundraising, #foss, #community
+     - Parent workstream (if nesting makes sense): select from existing or "top-level"
+   - **Batch:** Present a single combined question listing all workstreams with status options. Faster, but the user sees everything at once.
+6. **Create each workstream** — flags go OUTSIDE the quotes:
+   - `ws new "FinFam Product" --size week --tag code --tag business`
+   - The title is ONLY the name in quotes. Do NOT include --flags inside the quotes.
+   - For "snooze for next week" items: also run `ws snooze <id> next-week` after creating
+   - For "snooze for next month" items: also run `ws snooze <id> next-month` after creating
+7. **Nest where appropriate**: `ws nest <child-id> <parent-id>`
+8. **Continue reading** older files if the user wants to go deeper. Propose new workstreams as themes emerge from older notes.
+
+### Pass 2: Detailed Thought Extraction
+
+9. Once the user is satisfied with the workstream tree, run `ws sweep --discover` to do detailed thought-by-thought extraction. **Use a 300-second timeout** for this command — it processes files one at a time and saves progress after each, so it's safe to retry if interrupted. Run with `--interactive` for month-by-month review.
+10. After sweep completes, check if `_Workstreams/inbox.md` has unmatched thoughts.
+11. For inbox items: read the inbox, and for each thought ask whether it fits one of the new workstreams or should stay in inbox for later triage.
+
+### Wrap-up
+
+12. Run `ws tree` to show the final hierarchy
+13. Summarize what was created: N workstreams, their statuses, and the nesting structure
+14. Ask: "Want to continue exploring, or are we done?"
+15. If done, tell the user:
+    - The **workstream-review** skill is available for ongoing management
+    - They can run `ws sweep --discover` anytime to process new sprint notes
+    - Use `ws list`, `ws next`, `ws stale` for day-to-day prioritization
+    - Exit this session with Ctrl+C or /exit
+
+## Guidelines
+
+- **Ask before creating** — don't batch-create without confirmation
+- **Prefer broader workstreams** over many narrow ones (5-15 is typical for 60 days)
+- **Ideas are cheap** — encourage capturing them with `ws idea <parent-id> <text>` on relevant workstreams. If a standalone workstream isn't active now, snooze it rather than skipping it.
+- **Keep `ask` batches small** (5-7 options max) — the tool has a short input timeout and large lists get auto-selected before the user can respond
+- **Work newest-first** — recent work is freshest in the user's mind
+- **Don't read every file** — 2-3 files at a time, propose themes, then go deeper if the user wants
+- **Respect the user's time** — if they want to stop early, that's fine. Progress is saved.