personamanagmentlayer__pcl/.github/copilot-instructions.md

GitHub Copilot Instructions for PCL (Persona Control Language)

Project Overview

PCL (Persona Control Language) is a domain-specific programming language and compiler for AI persona management. This is a TypeScript-based compiler project that includes:

• Lexer: Tokenization and scanning
• Parser: AST generation from tokens
• Semantic Analysis: Type checking, validation, and symbol resolution
• Runtime: Execution engine for PCL programs
• Standard Library: Built-in personas, types, and utilities
• CLI: Command-line interface for PCL tools

Tech Stack: TypeScript 5.3+, Node.js, ESM modules, Vitest for testing

PCL Bootstrap System

Important: This project includes a PCL-Lite Bootstrap system that enables AI assistants to interpret /persona commands for multi-persona collaboration.

• Bootstrap File: ../.roadmap/bootstrap/BOOTSTRAP_EN.md
• Purpose: Embedded runtime v1.0 for AI chat interfaces (ChatGPT, Claude, Gemini, etc.)
• Personas: 25+ built-in personas (ARCHI, SEC, DEV, DEVOPS, CRITIC, etc.) with specialized skills
• Commands: 120+ /persona commands for activation, composition, teams, workflows, and more
• Domain Focus: Standardization personas (STANDARD_ARCHITECT, SPEC_EDITOR, COMPLIANCE_ENGINEER, etc.)

When working on PCL code generation, reference the bootstrap specification to understand the target runtime behavior and persona system that PCL compiles to.

Key Bootstrap Concepts:

• Persona Activation: /persona [id] - Activate a persona with specialized capabilities
• Team Composition: /team [id] - Load pre-configured teams (e.g., security-review, dream-team, standardization)
• Shared Skills: Personas inherit foundation, technical, security, architecture, standards, and tools skills
• Merge Modes: primary, consensus, weighted, sequential, parallel for multi-persona responses
• Workflow Orchestration: Define and execute multi-step workflows with persona handoffs

---

Core Architecture Principles

1. Compiler Pipeline

Source Code → Lexer → Parser → Semantic Analyzer → Codegen → Runtime

• Each phase is pure and testable
• Errors are collected, not thrown (use Result<T, Error[]> pattern)
• Transformations are immutable (return new AST nodes, don't mutate)
• Position tracking is mandatory for all AST nodes (for error messages)

2. Type System

• Strongly typed with TypeScript
• Use discriminated unions for AST nodes (e.g., type: 'PersonaDeclaration')
• Leverage branded types for identifiers (e.g., PersonaId, SkillId)
• Nominal typing over structural where semantics matter

3. Error Handling

// ✅ GOOD: Return Result type
function parse(input: string): Result<AST, ParseError[]> {
  const errors: ParseError[] = [];
  // ... collect errors
  if (errors.length > 0) {
    return { ok: false, errors };
  }
  return { ok: true, value: ast };
}

// ❌ BAD: Throw exceptions in compiler code
function parse(input: string): AST {
  throw new Error('Parse failed'); // Don't do this
}

---

Coding Standards

TypeScript Guidelines

1. Strict Mode Always

   // tsconfig.json has strict: true
   // No implicit any, no unused variables, etc.
   

2. Prefer const over let

   const tokens = lexer.scan(source); // ✅
   let tokens = lexer.scan(source); // ❌
   

3. Use Readonly for Immutability

   interface ASTNode {
     readonly type: string;
     readonly position: Position;
     readonly children: readonly ASTNode[]; // ✅
   }
   

4. Discriminated Unions for AST

   type Expression =
     | { type: 'Identifier'; name: string }
     | { type: 'Literal'; value: string | number }
     | { type: 'BinaryOp'; left: Expression; op: string; right: Expression };
   
   function evaluate(expr: Expression): Value {
     switch (
       expr.type // Type narrowing works!
     ) {
       case 'Identifier':
         return lookupVariable(expr.name);
       case 'Literal':
         return expr.value;
       case 'BinaryOp':
         return evalBinaryOp(expr);
     }
   }
   

5. Brand Types for Domain Concepts

   type PersonaId = string & { readonly __brand: 'PersonaId' };
   type SkillId = string & { readonly __brand: 'SkillId' };
   
   function createPersonaId(id: string): PersonaId {
     return id as PersonaId;
   }
   

6. Avoid any, Use unknown Instead

   function processInput(input: unknown) {
     // ✅
     if (typeof input === 'string') {
       // TypeScript knows input is string here
     }
   }
   
   function processInput(input: any) {
     // ❌
     // Loses all type safety
   }
   

Naming Conventions

• Files: kebab-case.ts (e.g., persona-parser.ts)
• Classes: PascalCase (e.g., PersonaDeclaration)
• Interfaces: PascalCase (e.g., Lexer, Parser)
• Functions: camelCase (e.g., parsePersona, validateSkills)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_PERSONAS, TOKEN_TYPES)
• Types/Interfaces: PascalCase (e.g., ASTNode, Token)
• Enums: PascalCase for enum, PascalCase for members

  enum TokenType {
    Identifier = 'IDENTIFIER',
    Keyword = 'KEYWORD',
  }
  

File Structure

src/
  ├── lexer/
  │   ├── index.ts          # Public API exports
  │   ├── lexer.ts          # Lexer class
  │   ├── token.ts          # Token types
  │   └── scanner.ts        # Character scanning utilities
  ├── parser/
  │   ├── index.ts          # Public API
  │   ├── parser.ts         # Parser class
  │   ├── ast.ts            # AST node definitions
  │   └── grammar.ts        # Grammar rules
  ├── semantic/
  │   ├── index.ts
  │   ├── type-checker.ts   # Type checking
  │   ├── symbol-table.ts   # Symbol resolution
  │   └── validator.ts      # Semantic validation
  ├── runtime/
  │   ├── index.ts
  │   ├── interpreter.ts    # Execute AST
  │   └── environment.ts    # Runtime environment
  ├── stdlib/
  │   ├── index.ts
  │   └── personas.ts       # Built-in personas
  ├── types/
  │   ├── index.ts
  │   ├── persona.ts        # Persona type definitions
  │   └── skill.ts          # Skill type definitions
  └── cli/
      ├── index.ts
      └── commands.ts       # CLI command handlers

---

Common Patterns

1. Visitor Pattern for AST Traversal

interface ASTVisitor<T> {
  visitPersonaDeclaration(node: PersonaDeclaration): T;
  visitSkillDeclaration(node: SkillDeclaration): T;
  visitTeamDeclaration(node: TeamDeclaration): T;
}

class TypeChecker implements ASTVisitor<Type> {
  visitPersonaDeclaration(node: PersonaDeclaration): Type {
    // Type check persona
  }
}

2. Builder Pattern for Complex Objects

class PersonaBuilder {
  private persona: Partial<Persona> = {};

  withId(id: PersonaId): this {
    this.persona.id = id;
    return this;
  }

  withSkills(skills: Skill[]): this {
    this.persona.skills = skills;
    return this;
  }

  build(): Persona {
    if (!this.persona.id || !this.persona.skills) {
      throw new Error('Invalid persona');
    }
    return this.persona as Persona;
  }
}

3. Error Collection Pattern

class ErrorCollector {
  private errors: CompileError[] = [];

  addError(error: CompileError): void {
    this.errors.push(error);
  }

  hasErrors(): boolean {
    return this.errors.length > 0;
  }

  getErrors(): readonly CompileError[] {
    return this.errors;
  }
}

4. Position Tracking for All Nodes

interface Position {
  readonly line: number;
  readonly column: number;
  readonly offset: number;
}

interface SourceRange {
  readonly start: Position;
  readonly end: Position;
}

interface ASTNode {
  readonly type: string;
  readonly range: SourceRange; // Always include for error messages
}

---

Testing Guidelines

1. Test File Naming

• Test files: *.test.ts (e.g., lexer.test.ts)
• Place tests next to source files or in tests/ directory

2. Test Structure

import { describe, it, expect } from 'vitest';
import { Lexer } from './lexer';

describe('Lexer', () => {
  describe('tokenization', () => {
    it('should tokenize persona declaration', () => {
      const source = 'persona ARCHI { }';
      const lexer = new Lexer(source);
      const tokens = lexer.scan();

      expect(tokens).toHaveLength(4);
      expect(tokens[0].type).toBe('KEYWORD');
      expect(tokens[0].value).toBe('persona');
    });

    it('should handle invalid syntax', () => {
      const source = 'persona @invalid';
      const lexer = new Lexer(source);
      const result = lexer.scan();

      expect(result.ok).toBe(false);
      expect(result.errors).toHaveLength(1);
    });
  });
});

3. Test Coverage Requirements

• Minimum 80% coverage for all compiler code
• 100% coverage for critical paths (parser, type checker)
• Use npm run test:coverage to check

4. Test Data Organization

// fixtures/personas.pcl - Example PCL files for testing
// tests/fixtures/ - Test input files
// tests/snapshots/ - Expected outputs (use snapshot testing)

---

Documentation Standards

1. TSDoc Comments

/**
 * Parses a persona declaration from tokens.
 *
 * @param tokens - The token stream to parse
 * @returns The parsed persona AST node
 * @throws {ParseError} When syntax is invalid
 *
 * @example
 * ```typescript
 * const tokens = lexer.scan('persona ARCHI { }');
 * const ast = parsePersona(tokens);
 * ```
 */
export function parsePersona(tokens: Token[]): PersonaDeclaration {
  // ...
}

2. README for Each Module

src/lexer/README.md  → Explain lexer architecture
src/parser/README.md → Explain parser rules

3. Inline Comments

• Explain WHY, not WHAT
• Document edge cases and invariants

// We need to track both shared and specialized skills separately
// to maintain the skill hierarchy for inheritance
const sharedSkills = resolveSharedSkills(persona);

---

Anti-Patterns to Avoid

❌ Don't Mutate AST Nodes

// BAD
function transform(node: PersonaDeclaration) {
  node.skills.push(newSkill); // Mutating!
}

// GOOD
function transform(node: PersonaDeclaration): PersonaDeclaration {
  return {
    ...node,
    skills: [...node.skills, newSkill], // Immutable
  };
}

❌ Don't Use Global State

// BAD
let currentPersona: Persona | null = null;

// GOOD
class Parser {
  private currentPersona: Persona | null = null;
}

❌ Don't Skip Error Handling

// BAD
const ast = parse(source); // Might throw

// GOOD
const result = parse(source);
if (!result.ok) {
  console.error(result.errors);
  return;
}
const ast = result.value;

❌ Don't Mix Concerns

// BAD - Lexer doing semantic analysis
class Lexer {
  scan() {
    if (token.value === 'persona') {
      validatePersonaName(); // Wrong layer!
    }
  }
}

// GOOD - Separation of concerns
class Lexer {
  scan() {
    // Only tokenization
  }
}

class SemanticAnalyzer {
  analyze() {
    validatePersonaName(); // Right layer
  }
}

---

Compiler-Specific Guidelines

1. Lexer

• Single responsibility: Convert source to tokens
• No look-ahead: Process character by character
• Error recovery: Continue scanning after errors
• Position tracking: Maintain line/column for all tokens

2. Parser

• Recursive descent parsing style
• Top-down approach (parse program → declarations → expressions)
• Error recovery: Synchronize at statement boundaries
• Predictive parsing: Use lookahead(1) when possible

3. Semantic Analysis

• Two-pass: First pass for declarations, second for validation
• Symbol table: Track all declared personas, skills, teams
• Type checking: Validate skill references, persona composition
• Constraint checking: Ensure all invariants hold

4. Code Generation

• Target: JavaScript/TypeScript runtime code
• Optimizations: Inline constants, dead code elimination
• Source maps: Maintain mapping to original PCL source

5. Runtime

• Lazy evaluation: Don't execute until needed
• Memory safety: No memory leaks, cleanup after execution
• Sandboxing: Isolate persona execution contexts

---

Performance Guidelines

1. Avoid repeated parsing: Cache parsed ASTs
2. Use string interning: Deduplicate identical strings
3. Lazy initialization: Don't load stdlib until needed
4. Stream processing: Process large files in chunks
5. Memoization: Cache expensive computations (e.g., type checking)

// Memoization example
const typeCache = new Map<ASTNode, Type>();

function inferType(node: ASTNode): Type {
  if (typeCache.has(node)) {
    return typeCache.get(node)!;
  }
  const type = computeType(node);
  typeCache.set(node, type);
  return type;
}

---

Git Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, style, refactor, test, chore, perf

Examples:

feat(parser): add support for nested persona composition

- Implement recursive parsing for complex persona expressions
- Add validation for circular dependencies
- Update grammar documentation

Closes #42

fix(lexer): handle unicode identifiers correctly

Previously, non-ASCII characters in identifiers would cause
the lexer to crash. Now properly handles UTF-8 input.

Fixes #128

---

Copilot-Specific Tips

What to Suggest

✅ DO suggest:

• Type-safe AST transformations
• Comprehensive error handling with Result<T, E> types
• Immutable data structures
• Visitor pattern implementations
• Position tracking in AST nodes
• TSDoc documentation
• Unit tests with edge cases
• Performance optimizations (memoization, caching)

What NOT to Suggest

❌ DON'T suggest:

• Mutable AST node modifications
• Throwing exceptions in compiler code
• Global state or singletons
• any types without justification
• Missing position information in AST
• Tests without assertions
• Undocumented public APIs

---

Example Code Generation

When generating compiler code, follow this pattern:

// src/parser/expression-parser.ts

import type { Token } from '../lexer/token';
import type { Expression, BinaryExpression } from './ast';
import { TokenType } from '../lexer/token-type';
import type { ParseError } from './error';

/**
 * Parses a binary expression with operator precedence.
 *
 * Grammar:
 *   expression := term (('+' | '-') term)*
 *   term := factor (('*' | '/') factor)*
 *   factor := NUMBER | '(' expression ')'
 */
export class ExpressionParser {
  private current = 0;
  private errors: ParseError[] = [];

  constructor(private readonly tokens: readonly Token[]) {}

  parse(): Result<Expression, ParseError[]> {
    try {
      const expr = this.expression();

      if (this.errors.length > 0) {
        return { ok: false, errors: this.errors };
      }

      return { ok: true, value: expr };
    } catch (error) {
      // Unexpected error - should be handled by error collector
      this.errors.push(this.createError('Unexpected parse error'));
      return { ok: false, errors: this.errors };
    }
  }

  private expression(): Expression {
    return this.binary();
  }

  private binary(): Expression {
    let left = this.term();

    while (this.match(TokenType.Plus, TokenType.Minus)) {
      const operator = this.previous();
      const right = this.term();
      left = this.createBinaryExpression(left, operator, right);
    }

    return left;
  }

  private term(): Expression {
    // ... implementation
  }

  private match(...types: TokenType[]): boolean {
    for (const type of types) {
      if (this.check(type)) {
        this.advance();
        return true;
      }
    }
    return false;
  }

  private check(type: TokenType): boolean {
    if (this.isAtEnd()) return false;
    return this.peek().type === type;
  }

  private advance(): Token {
    if (!this.isAtEnd()) this.current++;
    return this.previous();
  }

  private isAtEnd(): boolean {
    return this.peek().type === TokenType.EOF;
  }

  private peek(): Token {
    return this.tokens[this.current];
  }

  private previous(): Token {
    return this.tokens[this.current - 1];
  }

  private createBinaryExpression(
    left: Expression,
    operator: Token,
    right: Expression
  ): BinaryExpression {
    return {
      type: 'BinaryExpression',
      left,
      operator: operator.value,
      right,
      range: {
        start: left.range.start,
        end: right.range.end,
      },
    };
  }

  private createError(message: string): ParseError {
    const token = this.peek();
    return {
      message,
      position: token.range.start,
      severity: 'error',
    };
  }
}

// Type definitions
type Result<T, E> = { ok: true; value: T } | { ok: false; errors: E };

---

Quick Reference

Task	Pattern	Example
Parse AST	Visitor Pattern	class TypeChecker implements ASTVisitor
Error Handling	Result Type	Result<AST, Error[]>
Immutability	Spread Operator	{ ...node, skills: [...node.skills] }
Type Safety	Branded Types	type PersonaId = string & { __brand }
Testing	Vitest + Snapshot	expect(ast).toMatchSnapshot()
Documentation	TSDoc	/** @param tokens - Input tokens */

---

Resources

• TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/
• Compiler Design Patterns: Crafting Interpreters
• AST Explorer: https://astexplorer.net/
• Testing Guide: Vitest Docs

---

Remember: When in doubt, prioritize type safety, immutability, and clear error messages. PCL is a compiler project—correctness and maintainability are paramount!

---

🚀 High-Performance Copilot Usage

Maximize AI Assistant Efficiency

To get the best performance from GitHub Copilot and other AI assistants, follow these optimization strategies:

1. Token Efficiency Strategies

✅ DO: Batch Operations

Read src/parser/index.ts, src/semantic/index.ts, and src/codegen/index.ts
in parallel to understand the compiler pipeline.

❌ DON'T: Sequential Requests

Read src/parser/index.ts
[wait for response]
Now read src/semantic/index.ts
[wait for response]
Now read src/codegen/index.ts

✅ DO: Precise Context Loading

Load context for parser enhancement:

- grammar/pcl.ebnf (team syntax)
- src/parser/index.ts (current implementation)
- tests/integration.test.ts (test patterns)
  Then implement team declaration parsing.

❌ DON'T: Vague Requests

Fix the parser

2. Parallel Tool Invocation

CRITICAL: Always execute independent operations in parallel to maximize efficiency and minimize latency.

When you have independent operations, request them together:

✅ "Read these files in parallel:

- src/ast/index.ts
- src/types/index.ts
- src/stdlib/index.ts
  Then explain the type hierarchy."

✅ "Update in parallel:

- QUICK-STATUS.md (mark Phase 1.1 complete)
- pcl_todo.md (check off runtime tasks)
- ROADMAP.md (update progress)"

✅ "Execute simultaneously:

- Read file contents
- Search for patterns
- List directory contents
  Then synthesize findings."

✅ "Run these checks simultaneously:

- npm run lint
- npm run test
- tsc --noEmit"

✅ "Perform multi-file edits in parallel using multi_replace_string_in_file:

- Fix import statements across 5 files
- Update type definitions in 3 files
- Add missing exports in 2 files"

3. Context Window Optimization

Provide Upfront Context:

Context: Working on Phase 1.1 runtime engine (see ROADMAP.md).
Current status: Parser works for persona declarations only.
Goal: Add team declaration support.
Reference: grammar/pcl.ebnf lines 45-60 for syntax.

Implement team parsing following the persona parser pattern.

Use Reference Paths:

✅ "Follow the pattern in src/parser/index.ts parsePersona() method"
❌ "Do it like we did before"

4. Persona-Driven Development

Leverage the PCL Bootstrap system for specialized assistance:

For Architecture Work:

/persona ARCHI

Design the LSP server architecture. Reference:

- src/parser/index.ts (current architecture)
- src/semantic/index.ts (analysis patterns)
  Output: Architecture diagram + implementation plan

For Security Reviews:

/persona SEC

Review src/runtime/index.ts for:

- Code injection vulnerabilities
- Untrusted input handling
- Sandbox escape vectors
  Output: Security audit report + fixes

For Code Quality:

/persona CRITIC

Review PR changes against:

- copilot-instructions.md standards
- 80% test coverage requirement
- Immutability patterns
  Output: Actionable improvement list

For Documentation:

/persona TECH_WRITER

Document the new workflow execution feature:

- User guide in docs/guides/
- API reference in docs/api/
- Code examples in examples/
  Style: Follow existing docs/ structure

For Team Reviews:

/team dream-team

Review the new type system implementation:

- ARCHI: Architectural soundness
- SEC: Security implications
- DEV: Code quality
- CRITIC: Overall assessment
  Output: Consensus report with action items

5. Incremental Task Management

Use the manage_todo_list tool for complex work:

✅ "Create a todo list for implementing LSP support:

1.  Design server architecture
2.  Implement text synchronization
3.  Add completion provider
4.  Add diagnostics
5.  Add hover support
6.  Write integration tests

Start with task 1."

Then as you work:
✅ "Mark task 1 complete, start task 2"
✅ "Update todo - add subtask to task 3: handle edge cases"

6. Efficient Error Resolution

Compile-Time Errors:

✅ "Run npm run build, analyze errors, and fix them"
❌ "There are some errors"

✅ "Run tsc --noEmit, show me the first 5 errors with file paths"
✅ "Fix TypeScript errors in src/parser/ using multi_replace"

Runtime Errors:

✅ "Run npm test, identify failures, fix them in order of priority"
✅ "Debug test failure in lexer.test.ts line 45 - show context"

Linting Issues:

✅ "Run npm run lint:fix, then report remaining issues"
✅ "Fix all linting errors in src/ using batch edits"

7. Code Generation Optimization

For Large Implementations:

✅ "Phase 1: Design the WorkflowExecutor interface
Phase 2: Implement core execution logic
Phase 3: Add error handling
Phase 4: Write comprehensive tests

Execute each phase sequentially, confirming after each."

✅ "Generate parser for skill declarations:

- Follow grammar/pcl.ebnf syntax
- Match src/parser/index.ts patterns
- Include error recovery
- Add position tracking
- Generate tests
  Use multi_replace for efficiency."

8. Smart File Operations

Reading Files:

✅ "Read lines 1-50, 200-250, 500-550 from src/parser/index.ts"
(Target specific sections)

❌ "Read the whole file" (when you only need specific parts)

Editing Files:

✅ Use multi_replace_string_in_file for multiple changes
✅ Provide 3-5 lines of context before/after changes
✅ Make changes atomic and testable

Searching:

✅ "Search for 'PersonaDeclaration' using grep (exact match)"
✅ "Semantic search: concepts related to type checking"
✅ "Find all \*.test.ts files"

9. Status and Progress Tracking

Regular Status Checks:

✅ "Quick status: What's complete, what's in progress, what's next?"
✅ "Compare current state vs ROADMAP.md Phase 1.1 goals"
✅ "Test coverage report: npm run test:coverage summary"

Progress Documentation:

✅ "Update QUICK-STATUS.md metrics after completing feature"
✅ "Add session summary to .roadmap/status/SESSION-SUMMARY.md"
✅ "Mark completed tasks in pcl_todo.md"

10. Quality Gates

Always include quality checks:

✅ "After implementation:

1.  Run npm run build (must pass)
2.  Run npm run test (must pass)
3.  Run npm run lint (must pass)
4.  Check test coverage ≥80%
5.  Verify 0 TypeScript errors
    Report: Pass/Fail for each gate"

---

⚙️ VS Code High-Performance Configuration

Recommended Settings

Add these to .vscode/settings.json:

{
  // ========================================
  // COPILOT OPTIMIZATION
  // ========================================
  "github.copilot.enable": {
    "*": true,
    "yaml": true,
    "plaintext": false,
    "markdown": true,
  },
  "github.copilot.advanced": {
    "debug.overrideEngine": "claude-sonnet-4.5",
    "debug.testOverrideProxyUrl": "",
    "debug.overrideProxyUrl": "",
  },

  // ========================================
  // TYPESCRIPT PERFORMANCE
  // ========================================
  "typescript.tsserver.maxTsServerMemory": 4096,
  "typescript.suggest.autoImports": true,
  "typescript.updateImportsOnFileMove.enabled": "always",
  "typescript.inlayHints.parameterNames.enabled": "all",
  "typescript.inlayHints.variableTypes.enabled": true,
  "typescript.preferences.importModuleSpecifier": "relative",

  // ========================================
  // EDITOR PRODUCTIVITY
  // ========================================
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true,
    "source.organizeImports": true,
  },
  "editor.bracketPairColorization.enabled": true,
  "editor.guides.bracketPairs": true,
  "editor.inlineSuggest.enabled": true,
  "editor.quickSuggestions": {
    "other": true,
    "comments": false,
    "strings": true,
  },

  // ========================================
  // FILE WATCHER OPTIMIZATION
  // ========================================
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/node_modules/**": true,
    "**/dist/**": true,
    "**/coverage/**": true,
    "**/.vscode-test/**": true,
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/coverage": true,
    "**/.vscode-test": true,
  },

  // ========================================
  // TESTING INTEGRATION
  // ========================================
  "vitest.enable": true,
  "vitest.commandLine": "npm run test",

  // ========================================
  // PCL LANGUAGE SUPPORT
  // ========================================
  "files.associations": {
    "*.pcl": "pcl",
    "*.ebnf": "plaintext",
  },

  // ========================================
  // TASK AUTOMATION
  // ========================================
  "task.autoDetect": "on",
  "task.saveBeforeRun": "always",
}

Essential Extensions

Add these to .vscode/extensions.json:

{
  "recommendations": [
    // ===== CORE DEVELOPMENT =====
    "github.copilot",
    "github.copilot-chat",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",

    // ===== TYPESCRIPT ENHANCEMENT =====
    "ms-vscode.vscode-typescript-next",
    "usernamehw.errorlens",
    "streetsidesoftware.code-spell-checker",

    // ===== TESTING =====
    "vitest.explorer",
    "hbenl.vscode-test-explorer",

    // ===== GIT WORKFLOW =====
    "eamodio.gitlens",
    "github.vscode-pull-request-github",

    // ===== DOCUMENTATION =====
    "yzhang.markdown-all-in-one",
    "bierner.markdown-mermaid",
    "shd101wyy.markdown-preview-enhanced",

    // ===== PRODUCTIVITY =====
    "gruntfuggly.todo-tree",
    "wayou.vscode-todo-highlight",
    "aaron-bond.better-comments",

    // ===== CODE QUALITY =====
    "mkaufman.count-lines-of-code",
    "ryanluker.vscode-coverage-gutters",
    "pflannery.vscode-versionlens"
  ]
}

Task Automation Setup

Enhance .vscode/tasks.json with shortcuts:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "🚀 Quick Start",
      "type": "shell",
      "command": "npm install && npm run build",
      "group": "none",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    },
    {
      "label": "✅ Quality Gate",
      "dependsOn": ["npm: lint", "tsc: check", "npm: test"],
      "dependsOrder": "sequence",
      "group": "test",
      "problemMatcher": []
    },
    {
      "label": "🔍 Pre-Commit Check",
      "type": "shell",
      "command": "npm run lint:fix && npm run format && npm run test",
      "group": "none",
      "presentation": {
        "reveal": "always"
      }
    },
    {
      "label": "📊 Coverage Report",
      "type": "shell",
      "command": "npm run test:coverage && start coverage/index.html",
      "group": "test",
      "windows": {
        "command": "npm run test:coverage ; start coverage/index.html"
      }
    }
  ]
}

Debugging Configuration

Enhance .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "🐛 Debug Current Test",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/vitest",
      "args": ["${file}"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "🧪 Debug All Tests",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "test"],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "🎯 Debug Parser",
      "program": "${workspaceFolder}/src/parser/index.ts",
      "preLaunchTask": "npm: build",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

Keyboard Shortcuts

Add to .vscode/keybindings.json:

[
  {
    "key": "ctrl+shift+t",
    "command": "workbench.action.tasks.runTask",
    "args": "npm: test"
  },
  {
    "key": "ctrl+shift+b",
    "command": "workbench.action.tasks.build"
  },
  {
    "key": "ctrl+shift+q",
    "command": "workbench.action.tasks.runTask",
    "args": "✅ Quality Gate"
  },
  {
    "key": "ctrl+k ctrl+d",
    "command": "github.copilot.generate"
  },
  {
    "key": "ctrl+k ctrl+i",
    "command": "github.copilot.interactiveEditor.explain"
  }
]

---

📊 Performance Metrics

Track these metrics for optimal workflow:

Metric	Target	Command
Build Time	< 10s	npm run build
Test Time	< 30s	npm run test
Type Check	< 5s	tsc --noEmit
Lint Check	< 3s	npm run lint
Test Coverage	≥ 80%	npm run test:coverage
Bundle Size	< 1MB	du -sh dist/

---

🎯 Quick Command Reference

High-Performance Workflows

# Full quality check (run before commits)
npm run lint:fix && npm run format && npm run test && npm run build

# Watch mode for development
npm run dev          # Build + watch
npm run test:watch   # Test + watch

# Coverage with HTML report
npm run test:coverage && open coverage/index.html

# Type check only (fast feedback)
npx tsc --noEmit

# Clean rebuild
npm run clean && npm run build

Copilot Power Commands

# Architecture planning

/persona ARCHI - Design [feature] architecture following src/ patterns

# Implementation

/persona DEV - Implement [feature] with tests following copilot-instructions.md

# Code review

/persona CRITIC - Review changes against quality standards

# Security audit

/persona SEC - Security review of [component]

# Documentation

/persona TECH_WRITER - Document [feature] in docs/

# Team review

/team dream-team - Comprehensive review of [PR/feature]

# Standards work

/team standardization - Review PCL language spec compliance

---

🔥 Pro Tips Summary

1. Batch operations - Request multiple reads/writes in parallel
2. Precise context - Provide file paths, line ranges, specific goals
3. Use personas - Activate specialized AI personas for focused tasks
4. Track progress - Use manage_todo_list for complex work
5. Quality gates - Always run lint + test + build after changes
6. Reference patterns - Point to existing code as templates
7. Multi-replace - Use multi_replace_string_in_file for efficiency
8. Targeted reads - Read specific line ranges, not entire files
9. Status sync - Keep ROADMAP.md, pcl_todo.md, QUICK-STATUS.md updated
10. Test coverage - Maintain ≥80% coverage, check with npm run test:coverage

---

Performance Mantra: "Batch operations, precise context, quality gates, track progress."