rtl-p4-block-parallel

Files (1)

• SKILL.md

SKILL.md (first lines)

<Purpose>
Execute Phase 4 RTL implementation using block-parallel worktree strategy with Claude Code
native team infrastructure. Each of 6 codec blocks (entropy, tq, me, mc, intra, filter)
develops in an isolated git worktree, then merges upstream-first with contract test
verification at each merge point. The skill (main session) handles team lifecycle:
TeamCreate, coordinator + worker spawning, task monitoring, and cleanup.
</Purpose>

<Use_When>
- Phase 2 interfaces are frozen and Phase 3 uArch specs are complete
- User says "block parallel", "parallel blocks", "6-block implement"
- Video codec design with 6 independent blocks that benefit from worktree isolation
- Need maximum parallelism with merge-time contract verification
</Use_When>

<Do_Not_Use_When>
- Phase 2 interfaces not yet defined (run rtl-p2-arch-design first)
- Phase 3 uArch specs not complete (run rtl-p3-uarch-design first)
- Non-codec design without 6-block structure (use rtl-p4-implement-team instead)
- Single module only (use rtl-p4-implement for simpler flow)
- Only need a single module bug fix (use rtl-p4s-bugfix)
</Do_Not_Use_When>

## Prerequisites

Phase 2 interface freeze and Phase 3 uArch completion required:
- `rtl/pkg/codec_if_pkg.sv` must exist (Phase 2 interface package)
- At least one uArch spec in `docs/phase-3-uarch/` must exist

```python
# Soft advisory check — WARNING + fallback, NOT hard block
if not Glob("rtl/pkg/codec_if_pkg.sv"):
    print("WARNING: rtl/pkg/codec_if_pkg.sv not found — Phase 2 interfaces missing.")
    print("Falling back to rtl-p4-implement (sequential, non-team).")
    Skill(skill="rtl-agent-team:rtl-p4-implement", prompt=ARGUMENTS)
    return

if not Glob("docs/phase-3-uarch/*.md"):
    print("WARNING: docs/phase-3-uarch/ has no uArch specs — Phase 3 incomplete.")
    print("Falling back to rtl-p4-implement (sequential, non-team).")
    Skill(skill="rtl-agent-team:rtl-p4-implement", prompt=ARGUMENTS)
    return
```

## Resume Logic

Before starting fresh, check for existing state:

```python
# === Phase 0: Resume Check ===
state_path = ".rat/state/block-parallel-state.json"
state = Read(state_path)  # Returns None if not found

if state:
    # Verify safety conditions for resume
    current_hash = Bash("find rtl/pkg/ rtl/intf/ docs/phase-3-uarch/ -name '*.sv' -o -name '*.md' | sort | xargs sha256sum | sha256sum | cut -d' ' -f1")
    if current_hash != state["frozen_hash"]:
        print("WARNING: Design freeze hash mismatch. Starting fresh.")
        state = None

    if state:
        base_ok = Bash(f"git merge-base --is-ancestor {state['base_commit']} HEAD && echo yes || echo no")
        if base_ok.strip() != "yes":
            print("WARNING: Base commit not ancestor of HEAD. Starting fresh.")
            state = None

    if state:
        for block, info in state["blocks"].items():
            if info.get("worktree_path") and info["status"] != "merged":
                wt_exists = Bash(f"test -d \"{info['worktree_path']}\" && echo yes || echo no")
                if wt_exists.strip() != "yes":
                    print(f"WARNING: Worktree for {block} missing. Starting fresh.")
                    state = None
                    break
```

### Common Step 1: Team Creation

Both resume and fresh paths need a team (teams are session-scoped, not persistent).

```python
# ALL-OR-NOTHING: if TeamCreate fails, fall back entirely to sequential.
# At this point no worktrees or tasks have been created in THIS session, so cleanup is clean.
try:
    TeamCreate(team_name="p4-block-parallel", description="6-block parallel RTL implementation with worktree isolation")
except:
    print("WARNING: TeamCreate failed. Falling back to rtl-p4-implement (sequential, non-team).")
    Skill(skill="rtl-agent-team:rtl-p4-implement", prompt=ARGUMENTS)
    return

## Common Step 2: Write team-config.json
Write(".rat/state/team-config.json", json.dumps({
    "team_mode": true,
    "team_name": "p4-block-parallel",
    "leader_session_id": "<current_session_id>",
    "coordinator_name": "coordinator",
    "worker_count": 6,
    "phase": "p4",
    "created_at": ISO_TIMESTAMP
}))
```

### Branched: Fresh vs Resume

```python
if state:
    # === RESUME PATH ===
    # Restore runtime variables from saved state (worktrees already exist from prior session)
    blocks = list(state["blocks"].keys())
    merge_order = blocks
    frozen_hash = state["frozen_hash"]
    base_commit = state["base_commit"]
    project_root = Bash("git rev-parse --show-toplevel").strip()

    print(f"Resuming from phase: {state['phase']}, "
          f"blocks completed: {sum(1 for b in state['blocks'].values() if b['status'] == 'merged')}/6")

    # Re-create task graph (tasks are session-scoped, not persistent across sessions)
    for block in blocks:

From babyworm/rtl-agent-team, MIT.

More from babyworm/rtl-agent-team