interface TokenService {
  generate(claims: TokenClaims): Promise<string>;
  validate(token: string): Promise<TokenClaims | null>;
}

interface TokenClaims {
  sub: string;      // service identifier
  aud: string[];    // allowed audiences
  exp: number;      // expiration timestamp
}

async function generate(claims: TokenClaims): Promise<string> {
  const payload = { ...claims, iat: Date.now() };
  return jwt.sign(payload, config.secret, { algorithm: 'RS256' });
}

undefined

**This skill appends the body sections:**

```markdown

**Then this skill:**
1. Generates Acceptance Criteria (inline) and gets human validation
2. Generates Summary and Glossary to replace the placeholders

<!-- START_PHASE_2 -->

Bad structure (task-level — this belongs in implementation plans):

Design plans describe WHAT gets built. Implementation plans describe HOW to build it step-by-step.

**Phase count:**
- Target: 5-8 phases (sweet spot for planning)
- Maximum: 8 phases (hard limit for writing-plans skill)
- If >8 phases needed: Note that multiple implementation plans will be required

**Why <=8 phases matters:**
- writing-plans skill has hard limit of 8 phases per implementation plan
- Exceeding 8 phases forces user to scope or split
- This is by design to prevent overwhelming implementation plans

**If design needs >8 phases:**

Add note to Additional Considerations:
```markdown

undefined

<!-- START_PHASE_1 -->

**Functionality phase example:**
```markdown
<!-- START_PHASE_2 -->

Bad Phase definitions:

**Too vague:**
```markdown

**Too detailed (task-level):**
```markdown

The second example is doing implementation planning's job. Design plans stay at component level.

undefined

**Example - Bad:**
```markdown

undefined

undefined

**If no existing patterns:**
```markdown

**If diverging from existing patterns:**
```markdown

undefined

undefined

**Edge cases** - if non-obvious:
```markdown
**Edge cases:** Clock skew handled by 5-minute token validation window. Revoked tokens remain in database for 7 days for audit trail.

**Future extensibility:** Token claims structure supports adding user metadata (currently unused). Enables future human user authentication without architecture change.

undefined

**Why scoped:** Multiple plan-and-execute rounds accumulate tests in the same codebase. Scoped identifiers prevent collision—`oauth2-svc-authn.AC2.1` and `user-prof.AC2.1` are unambiguous. Implementation phases, task specs, and test names all use the full scoped identifier.

undefined

**Step 2: Dispatch extraction subagent**

Use the Task tool to generate Summary and Glossary:

**Step 3: Review omitted terms with user**

Before inserting the extracted sections, briefly mention the omitted terms to the user:

"Glossary includes [X terms]. Omitted as likely obvious: [list from subagent]. Let me know if any of those should be included."

Don't wait for approval — proceed to insert the sections. The user can hit escape and ask for adjustments if needed.

**Step 4: Replace placeholders**

Replace the Summary and Glossary placeholder comments with the subagent's output. Do not insert the Omitted Terms section — that was for your transparency message only.

**Step 5: Review and adjust**

Briefly review the generated sections for accuracy. The subagent may miss nuance from the conversation — adjust if needed, but prefer the subagent's version when it's accurate (it reflects what the document actually says, not what you remember).

git add docs/design-plans/YYYY-MM-DD-<topic>.md
git commit -m "$(cat <<'EOF'
docs: add [feature name] design plan

Completed brainstorming session. Design includes:
- [Key architectural decision 1]
- [Key architectural decision 2]
- [N] implementation phases
EOF
)"

Phase 3 (Definition of Done) completes
  -> User confirms Definition of Done
  -> File created with Title, Summary placeholder, DoD, AC placeholder, Glossary placeholder
  -> DoD captured at full fidelity

Brainstorming (Phase 4) completes
  -> Validated design exists in conversation
  -> User approved incrementally

Writing Design Plans (this skill)
  -> Append body: Architecture, Existing Patterns, Implementation Phases, Additional Considerations
  -> Add exact paths from investigation
  -> Create discrete phases (<=8)
  -> Generate Acceptance Criteria inline (success + failure cases for each DoD item)
  -> USER VALIDATES Acceptance Criteria
  -> Replace AC placeholder with validated criteria
  -> Dispatch subagent to generate Summary and Glossary
  -> Replace Summary/Glossary placeholders with generated content
  -> Commit to git

Writing Implementation Plans (next step)
  -> Reads this design document
  -> Uses phases as basis for detailed tasks
  -> Uses Acceptance Criteria to generate test-requirements.md
  -> Expects exact paths and structure