forge-server 0.1.0

package/plugin/skills/terminal-presentation/SKILL.md

@@ -0,0 +1,395 @@
+---
+name: terminal-presentation
+description: This skill should be used for ALL terminal output formatting across the forge system. It defines the universal output standard for agent communication, status updates, summaries, error reports, plan presentations, and all user-facing content. Every forge agent references this skill.
+user-invocable: false
+---
+
+# Terminal Presentation Skill
+
+## Purpose
+
+Define the universal output formatting standard for every agent in the Forge system. All user-facing content -- status updates, interview questions, plan summaries, error reports, verification results, and agent handoff messages -- must follow these rules. Consistency across agents builds trust and makes output scannable.
+
+---
+
+## Visual Hierarchy Rules
+
+### Horizontal Rules (`---`)
+
+Use `---` to separate major sections of output. Every top-level section boundary gets a horizontal rule. Do not use horizontal rules inside sections -- use headers or blank lines for sub-section separation.
+
+```
+---
+
+## Section One
+Content here.
+
+---
+
+## Section Two
+Content here.
+
+---
+```
+
+### Headers (`##` and `###`)
+
+Use `##` for primary sections and `###` for sub-sections. Do not use `#` (H1) in terminal output -- it is reserved for document titles in written files. Do not go deeper than `###` in terminal output; use bold text or indentation for further nesting.
+
+```
+## Primary Section
+
+### Sub-Section
+
+**Detail point**: Explanation here.
+```
+
+### Blockquotes (`>`)
+
+Use blockquotes for three purposes:
+1. **Decision points**: When presenting a decision that requires user input.
+2. **Callouts**: When highlighting a critical finding, warning, or constraint.
+3. **Emphasis**: When a single statement needs to stand apart from surrounding content.
+
+```
+> This is a decision point. Choose one of the following options.
+
+> WARNING: The existing database schema does not support multi-tenancy.
+> This will require a migration that affects all existing data.
+```
+
+Do not use blockquotes for general content. They lose their emphasis when overused.
+
+### Blank Lines
+
+Insert one blank line after every header. Insert one blank line between list items only when items are multi-line. Insert two blank lines before a horizontal rule section separator (one blank line + the rule itself). Do not stack blank lines -- two consecutive blank lines is the maximum.
+
+### Box-Drawing Characters
+
+Use Unicode box-drawing characters for emphasis boxes when presenting critical information, summary panels, or phase boundaries:
+
+```
+  ┌─────────────────────────────────────────────┐
+  │  VERIFICATION COMPLETE                      │
+  │  Status: PASSED                             │
+  │  Checks: 7/7                                │
+  │  Blockers: 0  Warnings: 2                   │
+  └─────────────────────────────────────────────┘
+```
+
+Reserve box-drawing for:
+- Final status summaries (pass/fail panels)
+- Phase transition markers
+- Critical alerts that must not be missed
+
+Do not use box-drawing for routine content. Overuse dilutes its emphasis.
+
+---
+
+## Agent Identification
+
+Every agent must identify itself at the start of its output. Use the agent's role name with a color marker.
+
+### Standard Agent Header Format
+
+```
+--- {ROLE} ---
+```
+
+Where `{ROLE}` is the agent's role name in uppercase (e.g., `STRATEGIST`, `ARCHITECT`, `INSPECTOR`, `DESIGNER`).
+
+Each agent has an assigned color for its frontmatter. When presenting in environments that support color (and only then), use the assigned color. In plain text environments, rely on the role name alone.
+
+Agent color assignments (from agent definitions):
+- **Strategist**: magenta
+- **Product Manager**: cyan
+- **Architect**: blue
+- **Designer**: green
+
+Additional agents should declare their color in their agent definition. When no color is assigned, default to no color styling.
+
+### Status Update Format
+
+When reporting status, use this structure:
+
+```
+--- {ROLE} ---
+Phase: {Current Phase}
+Status: {On Track | At Risk | Blocked}
+
+## Summary
+{2-4 sentences on what happened since last report}
+
+## Completed
+- {Item 1}
+- {Item 2}
+
+## Next Action
+- {What happens next}
+
+---
+```
+
+---
+
+## Interview Formatting
+
+When conducting interviews (using the **interviewing** skill), apply these formatting rules:
+
+### Opening Context Summary
+
+Before the first question, present a brief context block summarizing what is already known:
+
+```
+---
+
+## Interview: {Topic}
+
+> Context: {1-3 sentences summarizing what is known so far --
+> the vision, prior decisions, or the trigger for this interview.}
+
+---
+```
+
+### Question Presentation
+
+Present exactly one question per message. Frame each question with context from prior answers:
+
+```
+Based on your requirement for {X}, I want to clarify {Y}.
+
+**{Question text}**
+
+> A) **{Option label}** -- {Brief description of this option and its implications}
+> B) **{Option label}** -- {Brief description of this option and its implications}
+> C) **{Option label}** -- {Brief description of this option and its implications}
+> D) **Something else** -- Describe what you have in mind
+```
+
+Use descriptive option labels, not bare keywords. "A) Server-side rendering -- initial page load served by Node, hydrated on client" is better than "A) SSR."
+
+### Recap Formatting
+
+At the end of an interview round, present the recap as:
+
+```
+---
+
+## Interview Recap
+
+> Round {N} complete. Here is what we have established:
+
+### Decisions
+- **{Topic}**: {Decision} -- {Rationale}
+- **{Topic}**: {Decision} -- {Rationale}
+
+### Deferred
+- {Item}: {Why deferred}
+
+### Scope
+- **In**: {List of in-scope items}
+- **Out**: {List of out-of-scope items}
+
+> Does this accurately capture what we discussed? Anything to correct or add?
+
+---
+```
+
+---
+
+## Data Presentation
+
+### Lists Over Tables
+
+Prefer bulleted or numbered lists over tables for most data presentation. Lists are easier to scan in a terminal, wrap correctly at any width, and do not break when content varies in length.
+
+Use tables only when:
+- Data has 3+ columns that are meaningfully related.
+- Comparison across rows is the primary purpose (e.g., trade-off matrices, risk registers).
+- The content in each cell is short (under 30 characters per cell).
+
+### Table Formatting (When Used)
+
+Keep columns narrow. Abbreviate headers. Align columns with pipes and dashes. Do not attempt complex multi-line cells in terminal tables.
+
+```
+| Risk          | Likelihood | Impact | Mitigation           |
+|---------------|-----------|--------|----------------------|
+| Data loss     | Low       | High   | Automated backups    |
+| Auth bypass   | Medium    | High   | Pen test + code audit|
+```
+
+If a table would exceed 80 characters wide, either:
+1. Abbreviate content to fit.
+2. Split into multiple narrower tables.
+3. Convert to a list format with bold labels.
+
+### Code Blocks
+
+Always use fenced code blocks with a language tag when presenting code:
+
+````
+```typescript
+const result = await this.service.findAll();
+```
+````
+
+For shell commands, use `bash` or `sh` as the language tag:
+
+````
+```bash
+npm run db:generate && npm run db:migrate
+```
+````
+
+For file paths, configuration snippets, or structured data without a clear language, use `text`:
+
+````
+```text
+docs/plans/2026-02-25-notification-system/
+  vision.md
+  requirements.md
+  architecture.md
+  xd-plan.md
+```
+````
+
+### Progressive Disclosure
+
+When presenting complex information, use the bold-summary-then-detail pattern:
+
+```
+- **Authentication**: JWT-based with JWKS rotation.
+  Uses Auth0 as the identity provider. Tokens validated on every request
+  via the AuthGuard. Refresh tokens stored server-side with 7-day TTL.
+
+- **Authorization**: Role-based with resource-level permissions.
+  Three roles: admin, editor, viewer. Resource ownership checked at the
+  service layer. No client-side role enforcement.
+```
+
+The bold summary allows scanning. The indented detail is there for those who need it.
+
+---
+
+## Error and Warning Presentation
+
+### Severity Markers
+
+Use consistent severity markers for all error and warning output:
+
+```
+[BLOCKER]  {Description}  -->  {Suggested fix}
+[MAJOR]    {Description}  -->  {Suggested fix}
+[MINOR]    {Description}  -->  {Suggested fix}
+[INFO]     {Description}
+```
+
+### Error Report Structure
+
+When presenting verification failures, security findings, or build errors:
+
+```
+---
+
+## {Agent} Findings
+
+### Blockers (must fix before proceeding)
+- [BLOCKER] **{Location}**: {Description}
+  Fix: {Specific action to take}
+
+### Major Issues (should fix, may defer with justification)
+- [MAJOR] **{Location}**: {Description}
+  Fix: {Specific action to take}
+
+### Minor Issues (fix when convenient)
+- [MINOR] **{Location}**: {Description}
+
+### Passed Checks
+- {Check name}: PASSED
+- {Check name}: PASSED
+
+---
+```
+
+Always list passed checks after failures. Seeing what passed provides context for what failed and reassures the user that the non-failing areas were actually checked.
+
+---
+
+## Escalation to HTML
+
+Terminal formatting has limits. When content exceeds what the terminal can present clearly, generate an HTML file and reference it.
+
+### When to Escalate to HTML
+
+- **Tables with 4+ rows and 4+ columns**: Terminal tables become unreadable at this size.
+- **Architecture diagrams**: System topology, data flow diagrams, module dependency graphs.
+- **Complex comparison matrices**: Feature comparison tables, migration plans with multiple dimensions.
+- **Design system previews**: Color palettes, typography scales, component galleries.
+- **Timeline or Gantt-style views**: Phase plans with dependencies and parallel tracks.
+
+### How to Escalate
+
+1. Generate a self-contained HTML file (inline CSS, no external dependencies) using a clean, professional visual style.
+2. Write it to the plan folder: `docs/plans/{plan-folder}/{descriptive-name}.html`.
+3. In the terminal, present a brief summary and reference the file:
+
+```
+> Full architecture diagram written to:
+> `docs/plans/2026-02-25-notification-system/architecture-diagram.html`
+>
+> Open in a browser for the visual overview. Summary below:
+
+- 4 services: API Gateway, Notification Service, Email Worker, WebSocket Server
+- Message broker: SQS with DLQ for failed deliveries
+- Database: Shared RDS Postgres instance, separate schemas per service
+```
+
+The terminal gets the summary for quick scanning. The HTML file gets the full visual treatment. Use terminal for interaction; use HTML for complex presentation.
+
+---
+
+## Plan Presentation
+
+When presenting a completed plan document (vision, requirements, architecture, XD plan) for user review:
+
+1. Open with the document type and a one-line summary.
+2. Present each major section as a collapsible block (bold header + indented content).
+3. Highlight decision points or items needing user confirmation with blockquotes.
+4. End with an explicit prompt for approval or feedback.
+
+```
+---
+
+## Architecture Plan: Notification System
+
+> 8 modules, 14 API endpoints, 3 new database tables, 1 message queue.
+> Full plan written to `docs/plans/2026-02-25-notification-system/architecture.md`.
+
+### Modules
+- **NotificationModule**: Core notification CRUD and dispatch logic
+- **EmailWorkerModule**: SQS consumer for email delivery via SES
+- **WebSocketModule**: Real-time notification push to connected clients
+...
+
+### Key Decisions
+- **Message broker**: SQS over Redis Pub/Sub -- durability and DLQ support
+- **Email provider**: SES -- already in the AWS stack, no additional vendor
+
+> Ready to approve this plan? Or would you like to drill into any section?
+
+---
+```
+
+---
+
+## Formatting Anti-Patterns to Avoid
+
+- **Wall of text**: Never present more than 4-5 sentences without a visual break (header, list, blank line, or rule). If content is dense, restructure it as a list.
+- **Excessive decoration**: Do not use box-drawing, blockquotes, and bold all in the same section. Pick the one that best serves the content.
+- **Orphaned headers**: Never place a header with no content below it. If a section has nothing to report, write "None" or "N/A" below the header.
+- **Table abuse**: Do not use tables for 2-column key-value data. Use bold labels instead: `**Database**: PostgreSQL 15`.
+- **Unmarked code**: Never present code, commands, or file paths outside of fenced code blocks. Inline backticks are acceptable for short references within prose.
+- **Emoji in professional output**: Do not use emoji in any Forge agent output. Rely on text markers, box-drawing, and structural hierarchy for visual communication.
+- **Inconsistent severity markers**: Always use the standard markers (`[BLOCKER]`, `[MAJOR]`, `[MINOR]`, `[INFO]`). Do not invent new levels or use synonyms.
+- **Hiding critical information in paragraphs**: If something is a blocker, a decision point, or a status change, it must be in a visually distinct element (blockquote, list item with severity marker, or box). Never bury critical information in the middle of a paragraph.