@prmichaelsen/acp-visualizer 0.1.0

package/agent/design/requirements.template.md

@@ -0,0 +1,387 @@
+# Project Requirements
+
+**Project Name**: [Your Project Name]
+**Created**: YYYY-MM-DD
+**Status**: Draft | Active | Implemented
+
+---
+
+## Overview
+
+[Provide a high-level description of what this project is and what it aims to accomplish. This should be a clear, concise summary that anyone can understand.]
+
+**Example**: "A multi-tenant memory system that enables AI agents to store, retrieve, and manage contextual information across sessions with vector search capabilities and relationship tracking."
+
+---
+
+## Problem Statement
+
+[Describe the problem this project solves. What pain points or needs does it address?]
+
+**Example**: "AI agents currently have no persistent memory between sessions, leading to loss of context and requiring users to repeatedly provide the same information."
+
+---
+
+## Goals and Objectives
+
+[List the primary goals this project aims to achieve. Be specific and measurable where possible.]
+
+### Primary Goals
+1. Goal 1: [Description]
+2. Goal 2: [Description]
+3. Goal 3: [Description]
+
+### Secondary Goals
+1. Goal 1: [Description]
+2. Goal 2: [Description]
+
+**Example**:
+
+### Primary Goals
+1. Enable persistent memory storage across agent sessions
+2. Provide fast vector-based semantic search
+3. Support multi-tenant isolation for data security
+
+### Secondary Goals
+1. Implement relationship tracking between memories
+2. Add trust-based access control
+3. Support template-based memory creation
+
+---
+
+## Functional Requirements
+
+[List what the system must do. These are the features and capabilities.]
+
+### Core Features
+1. **Feature 1**: [Description of what it does]
+2. **Feature 2**: [Description of what it does]
+3. **Feature 3**: [Description of what it does]
+
+### Additional Features
+1. **Feature 1**: [Description]
+2. **Feature 2**: [Description]
+
+**Example**:
+
+### Core Features
+1. **Memory Storage**: Store structured memories with metadata (title, content, tags, timestamps)
+2. **Vector Search**: Find semantically similar memories using vector embeddings
+3. **Multi-Tenancy**: Isolate user data with per-user access control
+
+### Additional Features
+1. **Relationship Graph**: Track connections between related memories
+2. **Template System**: Pre-defined memory structures for common use cases
+3. **Trust Levels**: Control memory visibility based on trust scores
+
+---
+
+## Non-Functional Requirements
+
+[Describe quality attributes and constraints.]
+
+### Performance
+- Requirement 1: [Specific metric]
+- Requirement 2: [Specific metric]
+
+### Security
+- Requirement 1: [Security requirement]
+- Requirement 2: [Security requirement]
+
+### Scalability
+- Requirement 1: [Scalability requirement]
+- Requirement 2: [Scalability requirement]
+
+### Reliability
+- Requirement 1: [Reliability requirement]
+- Requirement 2: [Reliability requirement]
+
+**Example**:
+
+### Performance
+- Search queries return results in < 200ms for 95th percentile
+- Support 1000+ concurrent users
+
+### Security
+- Complete data isolation between tenants
+- All API endpoints require authentication
+- Sensitive data encrypted at rest
+
+### Scalability
+- Horizontal scaling for increased load
+- Support millions of memories per tenant
+
+### Reliability
+- 99.9% uptime SLA
+- Automatic backups every 24 hours
+- Graceful degradation under load
+
+---
+
+## Technical Requirements
+
+[Specify technical constraints and requirements.]
+
+### Technology Stack
+- **Language**: [Programming language and version]
+- **Framework**: [Framework and version]
+- **Database**: [Database technology]
+- **Infrastructure**: [Hosting/deployment platform]
+
+### Dependencies
+- Dependency 1: [Purpose]
+- Dependency 2: [Purpose]
+- Dependency 3: [Purpose]
+
+### Integrations
+- Integration 1: [What it integrates with and why]
+- Integration 2: [What it integrates with and why]
+
+**Example**:
+
+### Technology Stack
+- **Language**: TypeScript 5.x
+- **Runtime**: Node.js 20+
+- **Protocol**: Model Context Protocol (MCP)
+- **Vector DB**: Weaviate
+- **Document DB**: Firestore
+- **Authentication**: Firebase Auth
+
+### Dependencies
+- @modelcontextprotocol/sdk: MCP protocol implementation
+- weaviate-client: Vector database client
+- firebase-admin: Firestore and auth
+
+### Integrations
+- OpenAI API: Generate vector embeddings
+- Firebase Auth: User authentication and authorization
+
+---
+
+## User Stories
+
+[Describe functionality from the user's perspective.]
+
+### As a [User Type]
+1. I want to [action] so that [benefit]
+2. I want to [action] so that [benefit]
+3. I want to [action] so that [benefit]
+
+**Example**:
+
+### As an AI Agent
+1. I want to store memories about user preferences so that I can personalize responses
+2. I want to search for relevant memories so that I can provide contextual answers
+3. I want to create relationships between memories so that I can understand connections
+
+### As a User
+1. I want my data isolated from other users so that my privacy is protected
+2. I want to control which memories are shared so that I maintain control over my data
+3. I want to export my memories so that I can back them up
+
+---
+
+## Constraints
+
+[List any limitations or constraints on the project.]
+
+### Technical Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+### Business Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+### Resource Constraints
+- Constraint 1: [Description and impact]
+- Constraint 2: [Description and impact]
+
+**Example**:
+
+### Technical Constraints
+- Must use existing Firebase infrastructure
+- Vector embeddings limited to OpenAI models
+- MCP protocol requires stdio or SSE transport
+
+### Business Constraints
+- Must launch MVP within 3 months
+- Free tier must support 1000 memories per user
+- Must comply with GDPR and data privacy regulations
+
+### Resource Constraints
+- Single developer for initial implementation
+- Limited budget for cloud infrastructure
+- No dedicated QA team
+
+---
+
+## Success Criteria
+
+[Define what success looks like. How will you know the project is complete and successful?]
+
+### MVP Success Criteria
+- [ ] Criterion 1: [Measurable condition]
+- [ ] Criterion 2: [Measurable condition]
+- [ ] Criterion 3: [Measurable condition]
+
+### Full Release Success Criteria
+- [ ] Criterion 1: [Measurable condition]
+- [ ] Criterion 2: [Measurable condition]
+- [ ] Criterion 3: [Measurable condition]
+
+**Example**:
+
+### MVP Success Criteria
+- [ ] Users can create, read, update, and delete memories
+- [ ] Vector search returns relevant results
+- [ ] Multi-tenant isolation verified through security testing
+- [ ] Basic documentation complete
+
+### Full Release Success Criteria
+- [ ] All core and additional features implemented
+- [ ] Performance meets specified metrics
+- [ ] Security audit passed
+- [ ] 100 active users with positive feedback
+- [ ] Comprehensive documentation and examples
+
+---
+
+## Out of Scope
+
+[Explicitly list what is NOT included in this project to manage expectations.]
+
+1. Feature/capability 1: [Why it's out of scope]
+2. Feature/capability 2: [Why it's out of scope]
+3. Feature/capability 3: [Why it's out of scope]
+
+**Example**:
+
+1. **Mobile app**: Focus is on MCP server, not end-user applications
+2. **Real-time collaboration**: Single-user focus for MVP
+3. **Advanced analytics**: Basic usage stats only, no complex analytics
+4. **Custom embedding models**: OpenAI only for MVP
+5. **On-premise deployment**: Cloud-only for initial release
+
+---
+
+## Assumptions
+
+[List assumptions being made about the project.]
+
+1. Assumption 1: [Description]
+2. Assumption 2: [Description]
+3. Assumption 3: [Description]
+
+**Example**:
+
+1. Users have stable internet connectivity
+2. OpenAI API will remain available and affordable
+3. Firebase infrastructure will scale to meet demand
+4. MCP protocol will remain stable (no breaking changes)
+5. Users understand basic AI agent concepts
+
+---
+
+## Risks
+
+[Identify potential risks and mitigation strategies.]
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| [Risk 1] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+| [Risk 2] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+| [Risk 3] | High/Medium/Low | High/Medium/Low | [How to mitigate] |
+
+**Example**:
+
+| Risk | Impact | Probability | Mitigation Strategy |
+|------|--------|-------------|---------------------|
+| OpenAI API cost escalation | High | Medium | Implement caching, batch processing, consider alternative providers |
+| Security vulnerability | High | Low | Regular security audits, follow best practices, bug bounty program |
+| Performance degradation at scale | Medium | Medium | Load testing, performance monitoring, optimization plan |
+| MCP protocol changes | Medium | Low | Stay updated with MCP community, version pinning |
+
+---
+
+## Timeline
+
+[Provide a high-level timeline for the project.]
+
+### Phase 1: [Phase Name] (Duration)
+- Milestone 1
+- Milestone 2
+
+### Phase 2: [Phase Name] (Duration)
+- Milestone 3
+- Milestone 4
+
+### Phase 3: [Phase Name] (Duration)
+- Milestone 5
+- Milestone 6
+
+**Example**:
+
+### Phase 1: Foundation (Weeks 1-2)
+- Project setup and infrastructure
+- Basic MCP server implementation
+- Database connections
+
+### Phase 2: Core Features (Weeks 3-6)
+- Memory CRUD operations
+- Vector search implementation
+- Multi-tenant isolation
+
+### Phase 3: Advanced Features (Weeks 7-10)
+- Relationship tracking
+- Template system
+- Trust-based access control
+
+### Phase 4: Polish & Launch (Weeks 11-12)
+- Testing and bug fixes
+- Documentation
+- Deployment and monitoring
+
+---
+
+## Stakeholders
+
+[Identify who is involved in or affected by this project.]
+
+| Role | Name/Team | Responsibilities |
+|------|-----------|------------------|
+| [Role 1] | [Name] | [What they do] |
+| [Role 2] | [Name] | [What they do] |
+| [Role 3] | [Name] | [What they do] |
+
+**Example**:
+
+| Role | Name/Team | Responsibilities |
+|------|-----------|------------------|
+| Product Owner | [Name] | Define requirements, prioritize features |
+| Lead Developer | [Name] | Architecture, implementation, code review |
+| DevOps | [Name] | Infrastructure, deployment, monitoring |
+| Users | AI Agent Developers | Provide feedback, report issues |
+
+---
+
+## References
+
+[Link to related documents, research, or resources.]
+
+- [Document/Resource 1](URL): Description
+- [Document/Resource 2](URL): Description
+- [Document/Resource 3](URL): Description
+
+**Example**:
+
+- [Model Context Protocol Specification](https://modelcontextprotocol.io): MCP protocol documentation
+- [Weaviate Documentation](https://weaviate.io/developers/weaviate): Vector database docs
+- [Firebase Documentation](https://firebase.google.com/docs): Firebase platform docs
+- [Similar Project Analysis](URL): Research on existing solutions
+
+---
+
+**Status**: [Current status of requirements]
+**Last Updated**: [YYYY-MM-DD]
+**Next Review**: [YYYY-MM-DD]

package/agent/index/acp.core.yaml

@@ -0,0 +1,137 @@
+# agent/index/acp.core.yaml
+# Key file index for ACP core command directives
+# Bundled with acp-core package installs
+
+acp:
+  index:
+    - path: agent/commands/acp.proceed.md
+      weight: 0.9
+      kind: command
+      description: |
+        Primary task execution command. Defines how agents read tasks,
+        implement work, commit, and advance through milestones.
+      rationale: |
+        The most frequently invoked command. Agents must understand
+        autonomous mode, commit workflow, and progress tracking rules.
+      applies: acp.proceed, acp.plan, acp.task-create
+
+    - path: agent/commands/acp.init.md
+      weight: 0.8
+      kind: command
+      description: |
+        Session initialization command. Defines context loading sequence,
+        documentation reading, key file discovery, and status reporting.
+      rationale: |
+        Sets the foundation for every session. Agents need to understand
+        what init loads and what --quick/--skip flags control.
+      applies: acp.init, acp.plan
+
+    - path: agent/commands/acp.plan.md
+      weight: 0.8
+      kind: command
+      description: |
+        Planning command for milestone and task design. Defines how
+        agents break work into milestones, tasks, and implementation steps.
+      rationale: |
+        Required before creating milestones or tasks to ensure proper
+        scoping, sequencing, and design document references.
+      applies: acp.plan, acp.task-create, acp.design-create
+
+    - path: agent/commands/acp.task-create.md
+      weight: 0.8
+      kind: command
+      description: |
+        Task creation command. Defines task document structure, design
+        reference integration, and milestone assignment.
+      rationale: |
+        Tasks are the primary unit of work. Agents must follow the
+        creation steps including design cross-referencing (Step 5.5).
+      applies: acp.task-create, acp.proceed, acp.plan
+
+    - path: agent/commands/acp.command-create.md
+      weight: 0.7
+      kind: command
+      description: |
+        Command creation workflow. Defines namespace enforcement, draft
+        support, clarification capture, and package.yaml updates.
+      rationale: |
+        Ensures new commands follow template structure, include proper
+        directive headers, and are registered in package.yaml.
+      applies: acp.command-create, acp.plan
+
+    - path: agent/commands/acp.design-create.md
+      weight: 0.7
+      kind: command
+      description: |
+        Design document creation command. Defines how agents create
+        design specs from drafts, chat, or clarification context.
+      rationale: |
+        Design documents drive task creation. Agents must understand
+        the design-to-task pipeline and clarification capture.
+      applies: acp.design-create, acp.plan
+
+    - path: agent/commands/acp.clarification-create.md
+      weight: 0.7
+      kind: command
+      description: |
+        Clarification document creation. Defines question structure
+        (Items > Questions > Bullets), response markers, and overlap checks.
+      rationale: |
+        Clarifications are the primary requirements-gathering mechanism.
+        Agents must follow question format preferences (yes/no, discrete).
+      applies: acp.clarification-create, acp.clarification-address, acp.plan
+
+    - path: agent/commands/acp.clarification-address.md
+      weight: 0.6
+      kind: command
+      description: |
+        Addresses clarification responses with research, tradeoff
+        analysis, recommendations, and comment-block responses.
+      rationale: |
+        Defines how agents engage with user answers — when to research,
+        when to present tradeoffs, and comment-block conventions.
+      applies: acp.clarification-address, acp.proceed, acp.plan
+
+    - path: agent/commands/acp.clarification-capture.md
+      weight: 0.6
+      kind: command
+      description: |
+        Shared directive for capturing clarification decisions into
+        entity documents. Called by create commands, not directly by users.
+      rationale: |
+        Ensures design rationale is preserved in entities. Agents must
+        understand conflict resolution and Key Design Decisions format.
+      applies: acp.command-create, acp.design-create, acp.task-create, acp.pattern-create
+
+    - path: agent/commands/acp.design-reference.md
+      weight: 0.6
+      kind: command
+      description: |
+        Shared directive for design-to-task completeness. Ensures tasks
+        are self-contained with all design detail.
+      rationale: |
+        Prevents tasks from being underspecified. Agents must embed
+        design context into tasks rather than just linking to designs.
+      applies: acp.task-create, acp.proceed
+
+    - path: agent/commands/git.commit.md
+      weight: 0.7
+      kind: command
+      description: |
+        Intelligent commit workflow with version detection, changelog
+        updates, and conventional commit message formatting.
+      rationale: |
+        All version-bumping commits must follow this workflow. Defines
+        semver decision tree and CHANGELOG.md entry format.
+      applies: acp.proceed, git.commit
+
+    - path: agent/commands/acp.handoff.md
+      weight: 0.5
+      kind: command
+      description: |
+        Cross-context task handoff report generation. Defines how
+        agents create handoff reports for work transfer between contexts.
+      rationale: |
+        Reference when transferring work across projects or agents.
+        Defines freeform report format and target resolution.
+      applies: acp.handoff, acp.plan

package/agent/index/local.main.template.yaml

@@ -0,0 +1,37 @@
+# agent/index/local.main.yaml
+# Key file index for project-local files
+# See: agent/design/local.key-file-index-system.md
+#
+# Naming convention: {namespace}.{qualifier}.yaml
+#   - namespace: "local" for project files, package name for packages
+#   - qualifier: "main" is the default, can use others for categorization
+#
+# Schema:
+#   path        (string, required)  - Explicit file path, no globs
+#   weight      (float, required)   - 0.0 to 1.0 importance (1.0 = always read)
+#   kind        (enum, required)    - pattern, command, design, requirements
+#   description (string, required)  - What the file contains and why it matters
+#   rationale   (string, required)  - Why this file is in the index
+#   applies     (string, required)  - Comma-separated fully qualified command names
+#
+# Recommended limits:
+#   - Per-namespace: 5-10 entries maximum
+#   - Total across namespaces: 15-20 entries maximum
+#   - High-weight files (>= 0.8): 3-5 per namespace
+#
+# Implicit key files (NOT listed here):
+#   - AGENT.md (always read by @acp.init)
+#   - agent/progress.yaml (always read by @acp.init)
+
+local:
+  index:
+    - path: agent/design/requirements.md
+      weight: 1.0
+      kind: requirements
+      description: |
+        Core project requirements defining goals, constraints,
+        and success criteria for the application.
+      rationale: |
+        Must be read before any design or task creation to ensure
+        alignment with project goals.
+      applies: acp.init, acp.design-create, acp.task-create, acp.plan, acp.proceed

package/agent/manifest.template.yaml

@@ -0,0 +1,13 @@
+# agent/manifest.template.yaml
+# Template for ACP package manifest
+# This file tracks installed ACP packages and their versions
+
+# Installed packages
+# Each package entry tracks source, version, and installed files
+packages: {}
+
+# Manifest format version (for future compatibility)
+manifest_version: 1.0.0
+
+# Last time manifest was updated
+last_updated: null