desktop-team-doc 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# desktop-team-doc CLI
+
+CLI to install Desktop Team AI rules, skills, MCP, and commands into a project.
+
+## One-Shot Install (Recommended)
+
+Users who install the packaged CLI can run `install` **without** specifying a doc repo. The doc content is bundled in the package.
+
+```bash
+npm install -D desktop-team-doc
+npx desktop-team-doc install
+```
+
+The CLI will prompt you to select your AI environment (Cursor, Claude Code, Roo Code, or Gemini), then copy docs, rules, commands, skills, and agents to the appropriate location. Re-running install syncs files from the manifest, restoring deleted or modified files.
+
+## Install Structure
+
+Paths are relative to the target project directory (default: cwd).
+
+| Environment | docs | rules | commands | skills | agents | mcp |
+|--------------|------|-------|----------|--------|--------|-----|
+| **cursor** | `.cursor/docs` | `.cursor/rules` | `.cursor/commands/team` | `.cursor/skills` | `.cursor/agents` | `.cursor/mcp.json` (optional, `--mcp`) |
+| **claude** | `.claude/docs` | `.claude/rules` | `.claude/commands/team` | `.claude/skills` | `.claude/agents` | - |
+| **roo** | `.roo/rules/desktop-team-documentation` | - | - | - | - | `.cursor/mcp.json` (optional, `--mcp`) |
+| **gemini** | `.gemini/docs` | `.gemini/rules` | `.gemini/commands/team` | - | `.gemini/agents` | - |
+
+### docs/knowledge Structure
+
+Installed under `docs/knowledge`:
+
+| Subdirectory | Contents |
+|---------------|----------|
+| `architecture/` | Team-wide architecture patterns (audio-plugin, frontend-native-bridge, state-management) |
+| `development/` | Dev resources, glossary, API guides, project setup |
+| `environment-setup/` | Build machine, AAX signing, troubleshooting |
+| `projects/` | Project-specific knowledge (e.g. BIAS_ONE_GUI) |
+| `implementation-guides/` | How-to guides (adding amp, FX, cab, custom pedal) |
+| `component-library/` | Reusable component docs (ControlComponent, frontend-develop Skill) |
+| `domain/` | Domain concepts (signal-path, popup-system) |
+
+## Local Pack and Use in Another Project
+
+### 1. Build and Pack (from this repo)
+
+```bash
+cd tools/cli
+npm run pack:local   # Runs bundle, then packs
+```
+
+This bundles the doc content and produces `packages/desktop-team-doc-0.1.0.tgz`.
+
+### 2. Install CLI in Your Project
+
+```bash
+# From tarball
+npm install -D /path/to/desktop-team-documentation/tools/cli/packages/desktop-team-doc-0.1.0.tgz
+
+# Or from directory
+npm install -D file:../path/to/desktop-team-documentation/tools/cli
+```
+
+### 3. Install AI Docs
+
+```bash
+npx desktop-team-doc install
+```
+
+Content is bundled in the package.
+
+### 4. Verify
+
+```bash
+npx desktop-team-doc detect
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `desktop-team-doc install [options]` | Install Rules, Skills, Commands, MCP into current project |
+| `desktop-team-doc detect` | Show detected environment and install targets |
+| `desktop-team-doc uninstall` | Remove installed files and MCP config |
+
+## Install Options
+
+- `--target-dir=PATH` - Target project directory (default: cwd)
+- `--environment=cursor|claude|roo|all` - Override auto-detection
+- `--rules` / `--skills` / `--mcp` - Install only specific components
+- `--dry-run` - Preview what would be installed without making changes

package/content/docs/README.md

@@ -0,0 +1,227 @@
+# Desktop Team Documentation
+
+> **Architecture Version**: 1.0 (Context Engineering Model)
+> **Last Updated**: 2025-10-16
+
+This repository contains comprehensive documentation for the Desktop Team, structured using **Context Engineering** principles for optimal AI assistant integration and human readability.
+
+## 🎯 Quick Start
+
+**New to this documentation?** Start here:
+
+1. Read [index.md](./index.md) to understand the Context Engineering architecture
+2. Check [Instructions](#instructions-must-follow) for coding standards and workflows
+3. Explore [Knowledge](#knowledge-reference-information) for system architecture
+4. Use [Tools](#tools-automation) for automation and workflows
+
+## 📂 Repository Structure
+
+This repository is organized into three context types based on AI Engineering best practices:
+
+### `instructions/` - Context Type: Instructions
+
+**What**: Rules, standards, and processes that must be followed
+
+**Contains**:
+
+* [coding-conventions/](./instructions/coding-conventions/) - How code should be written
+  * [team-wide.md](./instructions/coding-conventions/team-wide.md) - Universal coding conventions
+  * [cpp.md](./instructions/coding-conventions/cpp.md) - C++ specific standards
+  * [frontend.md](./instructions/coding-conventions/frontend.md) - React/TypeScript/JavaScript frontend development
+  * [typescript.md](./instructions/coding-conventions/typescript.md) - TypeScript/JavaScript standards
+* [workflows/](./instructions/workflows/) - How work should be done
+  * [git-commit.md](./instructions/workflows/git-commit.md) - Git commit message standards
+  * [code-review.md](./instructions/workflows/code-review.md) - Code review process
+  * [jira-ticket-guide.md](./instructions/workflows/jira-ticket-guide.md) - How to create proper Jira tickets
+  * [jira-process.md](./instructions/workflows/jira-process.md) - JIRA automated workflow
+* [projects/](./instructions/projects/) - Project-specific guidelines
+  * [BIAS_ONE/coding-style.md](./instructions/projects/BIAS_ONE/coding-style.md) - BIAS_ONE coding style
+  * [BIAS_ONE/pg-log-guide.md](./instructions/projects/BIAS_ONE/pg-log-guide.md) - PG logging guide
+* [documentation-standards.md](./instructions/documentation-standards.md) - How to maintain documentation
+* [knowledge-base-management.md](./instructions/knowledge-base-management.md) - KB management rules
+
+### `knowledge/` - Context Type: Knowledge
+
+**What**: Factual information, architectural decisions, and domain expertise
+
+**Contains**:
+
+* [development/](./knowledge/development/) - Development resources, tech stack, glossary
+  * [tech-stack.md](./knowledge/development/tech-stack.md) - Development tech stack overview
+  * [glossary.md](./knowledge/development/glossary.md) - Variable naming and domain terminology
+* [environment-setup/](./knowledge/environment-setup/) - Build machines, CI/CD infrastructure setup
+  * [build-machine-setup.md](./knowledge/environment-setup/build-machine-setup.md) - Build machine setup guide
+  * [build-machine-troubleshooting.md](./knowledge/environment-setup/build-machine-troubleshooting.md) - Build machine troubleshooting
+  * [aax-signing-update.md](./knowledge/environment-setup/aax-signing-update.md) - AAX signing update guide
+* [architecture/](./knowledge/architecture/) - Architecture patterns & design principles (team-wide, reusable)
+* [component-library/](./knowledge/component-library/) - Reusable UI component documentation
+* [implementation-guides/](./knowledge/implementation-guides/) - How-to guides (adding amp, FX, cab, etc.)
+* [projects/](./knowledge/projects/) - Project-specific knowledge (e.g. BIAS_ONE_GUI)
+* [domain/](./knowledge/domain/) - Domain knowledge (audio DSP, plugin formats, etc.)
+
+### `tools/` - Context Type: Tools
+
+**What**: Executable tools, scripts, and automation
+
+**Contains**:
+
+* [agents/](./tools/agents/) - AI agent definitions
+  * [context-writer.md](./tools/agents/context-writer.md) - Interactive workflow for adding new documentation
+* [slash-commands/](./tools/slash-commands/) - Claude Code workflow commands
+  * [context-write.md](./tools/slash-commands/context-write.md) - Create new documentation
+  * [jira.md](./tools/slash-commands/jira.md) - JIRA ticket implementation
+  * [pr-gen.md](./tools/slash-commands/pr-gen.md) - Pull request generation
+  * [pr-review.md](./tools/slash-commands/pr-review.md) - Pull request review
+  * [commit.md](./tools/slash-commands/commit.md) - Standardized commits
+* [utilities/](./tools/utilities/) - Helper scripts and tools
+
+## 🚀 Integration with AI Code Assistants
+
+This documentation is optimized for AI assistant integration using Context Engineering principles.
+
+### Claude Code Integration
+
+#### 1. Reference Team Documentation
+
+Add to your `~/.claude/CLAUDE.md`:
+
+```markdown
+## Team Rules (Desktop Team)
+@/path/to/desktop-team-documentation/index.md
+```
+
+This allows Claude Code to automatically reference team guidelines with proper context type understanding.
+
+#### 2. Set Up Team Slash Commands
+
+```bash
+# Create the commands directory
+mkdir -p ~/.claude/commands
+
+# Create a symbolic link to team slash commands
+ln -s /path/to/desktop-team-documentation/tools/slash-commands ~/.claude/commands/team
+```
+
+**Available commands:**
+
+* `/team:context-write [topic?] [type?]` - Create new documentation (interactive workflow)
+* `/team:context-compress [mode?]` - Maintain repository quality (fix broken links, remove obsolete content)
+* `/team:jira [ticket-url-or-number]` - JIRA ticket implementation workflow
+* `/team:pr-gen [jira-tickets?] [target-branch?]` - Generate pull request
+* `/team:pr-review [pr-link-or-branch?]` - Review pull request
+* `/team:commit [repo-path?] [issue-number?]` - Standardized git commit
+
+### Roo Code Integration
+
+```bash
+# Create the .roo/rules directory
+mkdir -p <working_directory>/.roo/rules
+
+# Create a symbolic link
+ln -s /path/to/desktop-team-documentation <working_directory>/.roo/rules/desktop-team-documentation
+```
+
+## 📖 Usage Guide
+
+### For Developers
+
+**I want to...**
+
+* **Write code** → Check [instructions/coding-conventions/](./instructions/coding-conventions/)
+* **Understand workflows** → Check [instructions/workflows/](./instructions/workflows/)
+* **Learn architecture patterns** → Check [knowledge/architecture/](./knowledge/architecture/)
+* **Set up my environment** → Check [knowledge/development/](./knowledge/development/)
+* **Debug an issue** → Check [knowledge/debugging/](./knowledge/debugging/)
+* **Use automation tools** → Check [tools/](./tools/)
+
+### For AI Assistants
+
+When processing requests, load context based on type:
+
+1. **Generating/reviewing code?** → Load `instructions/coding-conventions/`
+2. **Understanding architecture patterns?** → Load `knowledge/architecture/`
+3. **Executing workflows?** → Load `tools/slash-commands/` or `tools/agents/`
+4. **Multiple needs?** → Load in priority: Instructions → Knowledge → Tools
+
+See [index.md](./index.md) for detailed guidance on context usage.
+
+## 🏗️ Architecture Principles
+
+This documentation structure implements:
+
+* **Context Management** - Write, Select, Compress, Isolate
+* **Failure Prevention** - No context poisoning, distraction, confusion, or clash
+* **AI Optimization** - Clear intent, efficient loading, reduced pollution
+* **Human Usability** - Easy navigation, clear organization, logical hierarchy
+
+For detailed explanation of the architecture, see [index.md](./index.md).
+
+## 🤝 Contributing
+
+### Adding New Content
+
+**Before adding content, determine the context type:**
+
+1. **Is it prescriptive?** (telling people what to do) → `instructions/`
+2. **Is it descriptive?** (explaining how things work) → `knowledge/`
+3. **Is it functional?** (providing automation) → `tools/`
+
+### Contribution Guidelines
+
+* Follow the established three-tier structure
+* Include "Last Updated" timestamps in file headers
+* Submit changes via pull request with review
+* Maintain cross-references between related content
+* Update [index.md](./index.md) when adding major sections
+
+## 🔄 Maintenance Schedule
+
+* **Instructions**: Review quarterly or when standards change
+* **Knowledge**: Update when architecture or design decisions change
+* **Tools**: Maintain when workflows evolve
+
+## 🆕 Setup for New Team Members
+
+1. **Clone this repository:**
+
+   ```bash
+   git clone git@github.com:Positive-LLC/desktop-team-documentation.git
+   ```
+
+2. **Read the architecture guide:**
+
+   Start with [index.md](./index.md) to understand the Context Engineering model
+
+3. **Set up AI assistant integration:**
+
+   Follow the [Integration](#integration-with-ai-code-assistants) instructions above
+
+4. **Review relevant documentation:**
+
+   * [Team-wide Coding Conventions](./instructions/coding-conventions/team-wide.md)
+   * Language-specific standards: [C++](./instructions/coding-conventions/cpp.md), [Frontend](./instructions/coding-conventions/frontend.md), [TypeScript](./instructions/coding-conventions/typescript.md)
+   * [Git Commit Convention](./instructions/workflows/git-commit.md)
+   * [Code Review Process](./instructions/workflows/code-review.md)
+   * [Architecture Patterns](./knowledge/architecture/) - Team-wide reusable patterns
+
+5. **Bookmark key documents**
+
+## 📝 Version History
+
+| Version | Date       | Changes                                   |
+|---------|------------|-------------------------------------------|
+| 2.0     | 2025-10-14 | Restructured to Context Engineering model |
+| 1.0     | 2025-05-13 | Initial flat structure                    |
+
+## 💬 Feedback
+
+For questions, suggestions, or major structural changes:
+
+* **Architecture Owner**: Gary Hsieh (<gary.hsieh@positivegrid.com>)
+* **Discussion**: Please discuss major structural changes with the team before implementation
+
+---
+
+**Team**: Positive Grid Desktop Team
+**Repository**: desktop-team-documentation
+**Architecture**: Context Engineering (v2.0)

package/content/docs/index.md

@@ -0,0 +1,352 @@
+# Desktop Team Documentation - Context Engineering Architecture
+
+> **Last Updated**: 2025-10-16
+> **Maintained by**: Positive Grid Desktop Team
+> **Architecture Version**: 1.0
+
+---
+
+## 🎯 Architecture Overview
+
+This documentation repository is structured based on **Context Engineering** principles, specifically designed for optimal AI assistant integration and human readability. The architecture follows the three fundamental context types defined in modern AI engineering practices.
+
+### Why This Structure?
+
+Traditional documentation often mixes "what to do" (instructions), "what we know" (knowledge), and "how to do it" (tools) in a single hierarchy, leading to:
+
+- **Context Confusion** - AI assistants struggle to distinguish between rules and reference information
+- **Context Distraction** - Irrelevant information dilutes critical context
+- **Inefficient Retrieval** - Harder for both humans and AI to locate the right information quickly
+
+By separating content into three distinct context types, we achieve:
+
+- **Clear Intent** - Each directory has a single, well-defined purpose
+- **Efficient Context Loading** - AI assistants can load only relevant context
+- **Scalable Organization** - Easy to maintain and extend as the team grows
+- **Better AI Performance** - Reduced context pollution and improved accuracy
+
+---
+
+## 📂 Three-Tier Context Architecture
+
+### 1. `instructions/` - Context Type: Instructions
+
+**Purpose**: Defines behavioral rules, standards, and processes that must be followed.
+
+**Content Type**: Prescriptive, normative, actionable
+
+**When to use**:
+
+- When you need to enforce coding standards
+- When defining workflows and processes
+- When setting team conventions
+
+**Structure**:
+
+```text
+instructions/
+├── coding-conventions/     # How code should be written
+│   ├── team-wide.md       # Universal rules across all languages
+│   ├── cpp.md             # C++ specific rules
+│   ├── frontend.md        # React/TypeScript/JavaScript frontend development
+│   └── typescript.md      # TypeScript/JavaScript specific rules
+├── workflows/             # How work should be done
+│   ├── git-commit.md      # Git commit message standards
+│   ├── code-review.md     # Code review process
+│   ├── jira-ticket-guide.md  # How to create proper Jira tickets
+│   └── jira-process.md    # JIRA automated workflow
+└── documentation-standards.md  # How to maintain this documentation
+```
+
+**AI Assistant Behavior**: When loading context from `instructions/`, AI should:
+
+- Treat content as strict rules to follow
+- Apply these standards when generating or reviewing code
+- Flag violations during code reviews
+- Prioritize these instructions over general knowledge
+
+**Example Use Cases**:
+
+- "Follow the team's C++ coding style when refactoring this class"
+- "Review this commit message against our standards"
+- "Generate code that adheres to our naming conventions"
+
+---
+
+### 2. `knowledge/` - Context Type: Knowledge
+
+**Purpose**: Stores factual information, architectural decisions, and domain expertise.
+
+**Content Type**: Descriptive, informational, contextual
+
+**When to use**:
+
+- When documenting system architecture
+- When explaining "why" decisions were made
+- When providing domain-specific background
+- When sharing debugging techniques
+
+**Structure**:
+
+```text
+knowledge/
+├── architecture/         # Architecture patterns & design principles (team-wide)
+├── development/          # Development resources, tech stack, glossary
+├── environment-setup/    # Build machines, CI/CD infrastructure setup
+├── projects/             # Project-specific knowledge (e.g. BIAS_ONE_GUI)
+├── implementation-guides/ # How-to guides (adding amp, FX, cab, etc.)
+├── component-library/    # Reusable UI component documentation
+└── domain/               # Domain knowledge (audio DSP, plugin formats, etc.)
+```
+
+**AI Assistant Behavior**: When loading context from `knowledge/`, AI should:
+
+- Use content for understanding and decision-making
+- Reference architectural patterns when designing solutions
+- Apply domain knowledge to problem-solving
+- Respect documented design decisions
+
+**Example Use Cases**:
+
+- "Explain the architecture of the preset management system"
+- "What are the common debugging techniques for audio glitches?"
+- "Why did we choose this particular state management approach?"
+
+---
+
+### 3. `tools/` - Context Type: Tools
+
+**Purpose**: Provides executable tools, scripts, and automation that extend capabilities.
+
+**Content Type**: Functional, executable, operational
+
+**When to use**:
+
+- When defining AI agents for specialized tasks
+- When creating workflow automation
+- When building reusable utilities
+
+**Structure**:
+
+```text
+tools/
+├── agents/               # AI agent definitions
+│   └── context-writer.md # Guide for adding new documentation
+├── slash-commands/       # Claude Code slash command scripts
+│   └── context-write.md  # Create new documentation workflow
+└── utilities/            # Helper scripts and tools
+```
+
+**AI Assistant Behavior**: When loading context from `tools/`, AI should:
+
+- Understand available capabilities and when to use them
+- Invoke appropriate tools for specific tasks
+- Follow tool-specific instructions and parameters
+- Compose tools to solve complex problems
+
+**Example Use Cases**:
+
+- "Use the PR review agent to analyze this pull request"
+- "Run the commit slash command to create a standardized commit"
+- "Check available agents for JIRA ticket processing"
+
+---
+
+## 🧠 Context Engineering Principles Applied
+
+This architecture implements key Context Engineering concepts:
+
+### Context Management Abstractions
+
+1. **Write (寫入)** - Clear pathways for adding new content
+   - New coding rule? → `instructions/coding-conventions/`
+   - New architecture doc? → `knowledge/architecture/`
+   - New automation? → `tools/`
+
+2. **Select (選擇)** - Easy filtering of relevant context
+   - Need rules? → Load `instructions/`
+   - Need background? → Load `knowledge/`
+   - Need capabilities? → Load `tools/`
+
+3. **Compress (壓縮)** - Eliminates redundancy and maintains quality
+   - Single source of truth for each topic
+   - No duplicate rules across files
+   - Clear hierarchy prevents overlap
+   - Rule-based pruning of invalid references, obsolete content, duplicate definitions, and structural violations
+   - Tool: `/team:context-compress` for automated maintenance and quality assurance
+
+4. **Isolate (隔離)** - Prevents context pollution
+   - Instructions don't mix with knowledge
+   - Tools are separate from rules
+   - Each directory has single responsibility
+
+### Avoiding Context Failure Modes
+
+- **No Context Poisoning** - Accurate, verified information only
+- **No Context Distraction** - Relevant information grouped together
+- **No Context Confusion** - Clear boundaries between types
+- **No Context Clash** - Hierarchical priority (instructions > knowledge > tools)
+
+---
+
+## 🔍 Navigation Guide
+
+### For AI Assistants
+
+When processing a request, determine the context type needed:
+
+1. **Generating or reviewing code?** → Load `instructions/coding-conventions/`
+2. **Understanding system design?** → Load `knowledge/architecture/`
+3. **Executing a workflow?** → Load `tools/slash-commands/` or `tools/agents/`
+4. **Multiple needs?** → Load contexts in order: Instructions → Knowledge → Tools
+
+### For Human Developers
+
+**I want to...**
+
+- Know how to write code → [`instructions/coding-conventions/`](./instructions/coding-conventions/)
+- Understand our workflows → [`instructions/workflows/`](./instructions/workflows/)
+- Learn system architecture → [`knowledge/architecture/`](./knowledge/architecture/) or [`knowledge/projects/`](./knowledge/projects/)
+- Set up development environment → [`knowledge/development/`](./knowledge/development/)
+- Set up build infrastructure → [`knowledge/environment-setup/`](./knowledge/environment-setup/)
+- Use available tools → [`tools/`](./tools/)
+- Debug an issue → [`knowledge/debugging/`](./knowledge/debugging/)
+
+---
+
+## 📚 Quick Reference
+
+### Instructions (Must Follow)
+
+**Coding Conventions:**
+
+- [Team-wide Coding Conventions](./instructions/coding-conventions/team-wide.md)
+- [C++ Coding Standards](./instructions/coding-conventions/cpp.md)
+- [Frontend Coding Standards](./instructions/coding-conventions/frontend.md)
+- [TypeScript Coding Standards](./instructions/coding-conventions/typescript.md)
+
+**Workflows:**
+
+- [Git Branch Convention](./instructions/workflows/git-branch-convention.md)
+- [Git Commit Convention](./instructions/workflows/git-commit.md)
+- [Code Review Process](./instructions/workflows/code-review.md)
+- [JIRA Ticket Guide](./instructions/workflows/jira-ticket-guide.md) - How to create proper Jira tickets
+- [JIRA Workflow](./instructions/workflows/jira-process.md) - Automated Jira processing workflow
+- [Scrum Process](./instructions/workflows/scrum-process.md)
+- [Survey Project Setup](./instructions/workflows/survey-project-setup.md)
+
+
+### Knowledge (Background Context)
+
+**Development Resources:**
+
+- [Tech Stack Overview](./knowledge/development/tech-stack.md)
+- [Development Glossary](./knowledge/development/glossary.md)
+- [AWS Storage Access](./knowledge/development/aws-storage.md)
+- [PG API Getting Started](./knowledge/development/pg-api-guide.md)
+- [Staging License Management](./knowledge/development/staging-license-management.md)
+- [CRM System Access](./knowledge/development/crm-system.md)
+- [Development Guide](./knowledge/development/)
+
+**Environment Setup:**
+
+- [Build Machine Setup](./knowledge/environment-setup/build-machine-setup.md) - 如何建置新的 build machine
+- [Build Machine Troubleshooting](./knowledge/environment-setup/build-machine-troubleshooting.md) - Build machine 常見問題排查
+- [AAX Signing Update](./knowledge/environment-setup/aax-signing-update.md) - AAX plugin 簽名認證更新
+- [Environment Setup Guide](./knowledge/environment-setup/)
+
+**Architecture & Patterns:**
+
+- [Architecture Patterns](./knowledge/architecture/)
+- [Domain Knowledge](./knowledge/domain/)
+- [Component Library](./knowledge/component-library/)
+- [Implementation Guides](./knowledge/implementation-guides/)
+- [Projects (BIAS_ONE_GUI)](./knowledge/projects/BIAS_ONE_GUI/)
+
+### Tools (Automation & Utilities)
+
+**Agents:**
+
+- [Context Writer Agent](./tools/agents/context-writer.md) - Interactive workflow for adding new documentation
+- [Context Compressor Agent](./tools/agents/context-compressor.md) - Repository maintenance through context trimming
+
+**Slash Commands:**
+
+- `/team:context-write` - [Create new documentation](./tools/slash-commands/context-write.md)
+- `/team:context-compress` - [Maintain repository quality](./tools/slash-commands/context-compress.md)
+- `/team:commit` - [Create git commit](./tools/slash-commands/commit.md)
+- `/team:jira` - [JIRA ticket workflow](./tools/slash-commands/jira.md)
+- `/team:pr-gen` - [Generate pull request](./tools/slash-commands/pr-gen.md)
+- `/team:pr-review` - [Review pull request](./tools/slash-commands/pr-review.md)
+
+**Utilities:**
+
+- [Pull Request Generation](./instructions/workflows/pull-request-generation.md)
+- [Code Review](./instructions/workflows/code-review.md)
+
+---
+
+## 🔄 Maintenance Guidelines
+
+### Adding New Content
+
+**Before adding any content, ask:**
+
+1. Is this prescriptive (telling people what to do)? → `instructions/`
+2. Is this descriptive (explaining how things work)? → `knowledge/`
+3. Is this functional (providing automation)? → `tools/`
+
+### Keeping Content Fresh
+
+- **Instructions**: Review quarterly or when standards change
+- **Knowledge**: Update when architecture or design decisions change
+- **Tools**: Maintain when workflows evolve
+
+### Version Control
+
+All changes to this documentation should be:
+
+- Committed with clear, descriptive messages
+- Reviewed by at least one team member
+- Tagged with update dates in file headers
+
+---
+
+## 🤝 Contributing
+
+When contributing to this documentation:
+
+1. **Respect the architecture** - Place content in the correct context type
+2. **Maintain clarity** - Use clear, concise language
+3. **Provide examples** - Include practical examples where helpful
+4. **Update index** - Keep this index.md current with new content
+5. **Cross-reference** - Link related content across context types
+
+---
+
+## 📖 Further Reading
+
+### Related Documentation
+
+- [README.md](./README.md) - Setup and integration instructions
+
+### Context Engineering Resources
+
+- Anthropic's Context Engineering Documentation
+- Modern AI Engineering Best Practices
+- Agentic Workflow Design Patterns
+
+---
+
+## 📝 Document History
+
+| Version | Date       | Changes                                      | Author      |
+|---------|------------|----------------------------------------------|-------------|
+| 2.0     | 2025-10-14 | Restructured to Context Engineering model    | Gary Hsieh  |
+| 1.0     | 2025-05-13 | Initial flat structure                       | Gary Hsieh  |
+
+---
+
+**Architecture Owner**: Gary Hsieh (<gary.hsieh@positivegrid.com>)
+**Team**: Positive Grid Desktop Team
+**Feedback**: Please discuss major structural changes with the team before implementation