@deimoscloud/coreai 0.1.0

package/src/skills/types.ts

@@ -0,0 +1,251 @@
+/**
+ * Skill Types
+ *
+ * Type definitions for skill generation and templates.
+ */
+
+import type { AdapterType } from '../adapters/types.js';
+
+/**
+ * Skill category
+ */
+export type SkillCategory = 'core' | 'optional' | 'custom';
+
+/**
+ * Integration dependency for a skill
+ */
+export interface SkillDependency {
+  /**
+   * Integration type required
+   */
+  type: AdapterType;
+
+  /**
+   * Whether this integration is required (vs optional)
+   */
+  required: boolean;
+
+  /**
+   * Description of why this integration is needed
+   */
+  description?: string;
+}
+
+/**
+ * Skill template definition
+ */
+export interface SkillTemplate {
+  /**
+   * Template name/identifier
+   */
+  name: string;
+
+  /**
+   * Human-readable description
+   */
+  description: string;
+
+  /**
+   * Hint for command arguments
+   */
+  argumentHint?: string;
+
+  /**
+   * Skill category
+   */
+  category: SkillCategory;
+
+  /**
+   * Integration dependencies
+   */
+  dependencies?: SkillDependency[];
+
+  /**
+   * Markdown content with placeholders
+   */
+  content: string;
+}
+
+/**
+ * Variables available for substitution in skill templates
+ */
+export interface SkillVariables {
+  // Project variables
+  PROJECT_NAME?: string;
+  PROJECT_ROOT?: string;
+  PROJECT_TYPE?: string;
+
+  // Issue tracker variables
+  JIRA_PROJECT?: string;
+  JIRA_URL?: string;
+  LINEAR_TEAM?: string;
+
+  // Git variables
+  GITHUB_REPO?: string;
+  GITHUB_OWNER?: string;
+  GITLAB_PROJECT?: string;
+  DEFAULT_BRANCH?: string;
+
+  // Documentation variables
+  CONFLUENCE_SPACE?: string;
+  CONFLUENCE_URL?: string;
+  NOTION_WORKSPACE?: string;
+  DOCS_PATH?: string;
+
+  // Quality gate commands
+  LINT_CMD?: string;
+  TEST_CMD?: string;
+  BUILD_CMD?: string;
+  STATIC_ANALYSIS_CMD?: string;
+
+  // Tech stack
+  PRIMARY_LANGUAGE?: string;
+
+  // Custom variables
+  [key: string]: string | undefined;
+}
+
+/**
+ * Options for generating skills
+ */
+export interface GenerateSkillsOptions {
+  /**
+   * Project root directory
+   */
+  projectRoot?: string;
+
+  /**
+   * Output directory for generated skills
+   * Default: .claude/commands
+   */
+  outputDir?: string;
+
+  /**
+   * Directory containing custom skill templates
+   */
+  customTemplatesDir?: string;
+
+  /**
+   * Whether to include core skills
+   * Default: true
+   */
+  includeCoreSkills?: boolean;
+
+  /**
+   * Whether to include optional skills based on integrations
+   * Default: true
+   */
+  includeOptionalSkills?: boolean;
+
+  /**
+   * Specific skills to generate (by name)
+   * If not specified, generates all applicable skills
+   */
+  skills?: string[];
+
+  /**
+   * Whether to overwrite existing skills
+   * Default: false
+   */
+  overwrite?: boolean;
+
+  /**
+   * Additional variables for substitution
+   */
+  variables?: Record<string, string>;
+}
+
+/**
+ * Result of generating a single skill
+ */
+export interface GeneratedSkill {
+  /**
+   * Skill name
+   */
+  name: string;
+
+  /**
+   * Category of the skill
+   */
+  category: SkillCategory;
+
+  /**
+   * Output path where skill was written
+   */
+  outputPath: string;
+
+  /**
+   * Whether the skill was newly created or updated
+   */
+  action: 'created' | 'updated' | 'skipped';
+
+  /**
+   * Reason for skipping (if applicable)
+   */
+  skipReason?: string;
+}
+
+/**
+ * Error from skill generation
+ */
+export interface SkillError {
+  /**
+   * Skill name that failed
+   */
+  name: string;
+
+  /**
+   * Error message
+   */
+  error: string;
+}
+
+/**
+ * Result of skill generation
+ */
+export interface GenerateSkillsResult {
+  /**
+   * Successfully generated skills
+   */
+  generated: GeneratedSkill[];
+
+  /**
+   * Skills that failed to generate
+   */
+  errors: SkillError[];
+
+  /**
+   * Variables used for substitution
+   */
+  variables: SkillVariables;
+}
+
+/**
+ * Skill configuration from coreai.config.yaml
+ */
+export interface SkillsConfig {
+  /**
+   * Whether to generate skills on build
+   */
+  generate?: boolean;
+
+  /**
+   * Custom skill templates directory
+   */
+  templatesDir?: string;
+
+  /**
+   * Skills to include (whitelist)
+   */
+  include?: string[];
+
+  /**
+   * Skills to exclude (blacklist)
+   */
+  exclude?: string[];
+
+  /**
+   * Custom variable overrides
+   */
+  variables?: Record<string, string>;
+}

package/templates/completion-report.md

@@ -0,0 +1,72 @@
+# Completion Report Template
+
+**Usage:** Engineer reports task completion to EM
+
+**Filename:** `YYYYMMDD_HHMM-[agent-name]-SUR-XX-complete.md`
+
+**Location:** `/KnowledgeLibrary/engineering-manager/inbox/`
+
+---
+
+```markdown
+---
+type: completion-report
+from: [agent-name]
+to: engineering-manager
+date: [YYYY-MM-DD HH:MM]
+ticket: SUR-XX
+priority: [P0 | P1 | P2 | P3]
+---
+
+## Completion: SUR-XX - [Title]
+
+### Summary
+[1-2 sentence summary of what was done]
+
+### PR
+- **URL:** [GitHub PR URL]
+- **CI Status:** Passing
+
+### Changes Made
+- [Change 1]
+- [Change 2]
+- [Change 3]
+
+### Acceptance Criteria
+- [x] Criterion 1 - [how addressed]
+- [x] Criterion 2 - [how addressed]
+- [x] Criterion 3 - [how addressed]
+
+### Quality Checks
+- [x] Tests passing: `./gradlew test`
+- [x] Lint passing: `./gradlew ktlintCheck`
+- [x] Static analysis passing: `./gradlew detekt`
+
+---
+
+## Workflow Checkpoint
+
+**Workflow:** Ticket Implementation
+**Ticket:** SUR-XX
+**Previous State:** IN_PROGRESS
+**Current State:** IN_REVIEW
+**Timestamp:** [YYYY-MM-DD HH:MM]
+
+### Entry Conditions Verified
+- [x] Ticket moved to "In Review" in Jira
+- [x] CI checks passing
+- [x] PR created with correct title format
+
+### Required Outputs Completed
+- [x] Code changes complete
+- [x] Unit tests written and passing
+- [x] Lint checks passing
+- [x] Static analysis passing
+- [x] All acceptance criteria addressed
+- [x] PR created: [URL]
+- [x] Jira updated with branch and PR comments
+
+### Next State
+**Target:** APPROVED (after review)
+**Blockers:** None
+```

package/templates/feedback.md

@@ -0,0 +1,56 @@
+# Feedback Template
+
+**Usage:** EM sends feedback when validation fails
+
+**Filename:** `YYYYMMDD_HHMM-engineering-manager-SUR-XX-feedback.md`
+
+**Location:** `/KnowledgeLibrary/[agent-name]/inbox/`
+
+---
+
+```markdown
+---
+type: feedback
+from: engineering-manager
+to: [agent-name]
+date: [YYYY-MM-DD HH:MM]
+ticket: SUR-XX
+priority: [P1 | P2]
+---
+
+## Feedback: SUR-XX - Validation Failed
+
+### Issue
+Your completion report for SUR-XX did not pass validation.
+
+### Problems Found
+
+1. **[Problem Category]**
+   - Expected: [what should be]
+   - Found: [what was actually found]
+   - Action needed: [what to do]
+
+2. **[Problem Category]**
+   - Expected: [what should be]
+   - Found: [what was actually found]
+   - Action needed: [what to do]
+
+### Common Issues
+
+- [ ] Ticket not in "In Review" status
+- [ ] PR URL missing from completion report
+- [ ] CI checks failing
+- [ ] Workflow checkpoint missing or incomplete
+- [ ] Acceptance criteria not addressed
+
+### Required Actions
+
+1. [Specific action 1]
+2. [Specific action 2]
+3. Send updated completion report to my inbox
+
+### References
+- Original task: [link to original assignment]
+- PR: [URL if exists]
+- Jira: https://[site].atlassian.net/browse/SUR-XX
+```

package/templates/project-files/CLAUDE.md.template

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+{{PROJECT_NAME}} - [Add brief project description]
+
+**Current State:** [e.g., Sprint 1 - Foundation]
+
+## Documentation
+
+All project documentation is maintained in Confluence: {{CONFLUENCE_URL}}/spaces/{{CONFLUENCE_SPACE}}
+
+### Key Documentation Pages
+
+| Section | Description |
+|---------|-------------|
+| **Product** | PRDs, product context, UI mockups |
+| **Architecture** | Technical architecture, data models |
+| **Development** | Environment setup, standards, CI/CD |
+| **Sprint Planning** | Current and past sprint plans |
+
+## Repository Structure
+
+```
+.claude/
+├── agents/              # Agent definitions
+├── commands/            # Slash commands (skills)
+└── mcp.json             # MCP server configuration
+
+KnowledgeLibrary/        # Agent context and communication
+├── context.txt          # Project state (EM updates)
+├── architecture.txt     # Architecture decisions
+├── prd.txt              # Product requirements
+└── [agent-name]/        # Per-agent directories
+    ├── inbox/           # Messages from other agents
+    ├── outbox/          # Sent messages
+    ├── context/         # Agent's current state
+    └── control/         # Objectives, decisions
+
+coreai/                  # Framework templates and scripts
+├── AGENT_SPEC.md        # Agent behavior specification
+├── WORKFLOWS.md         # Workflow state machines
+└── scripts/             # install.sh, add-agent.sh
+```
+
+## Development Skills
+
+Workflows are enforced through skills in `.claude/commands/`:
+
+| Skill | Description |
+|-------|-------------|
+| `/delegate` | EM delegates task to agent via inbox |
+| `/check-inbox` | Agent processes inbox tasks |
+| `/review` | EM requests PR review |
+| `/sprint-status` | EM generates sprint report |
+| `/git-commit` | Quality-gated commit (all checks must pass) |
+| `/pr-create` | Create PR and update Jira |
+
+## Code Quality
+
+Quality checks are enforced before every commit:
+
+```bash
+# Required checks (customize for your project)
+{{LINT_CMD}}
+{{TEST_CMD}}
+{{BUILD_CMD}}
+```
+
+## Agent Communication
+
+Agents communicate via file-based inbox system:
+1. Sender writes to `/KnowledgeLibrary/[recipient]/inbox/`
+2. User invokes recipient agent via `@[agent-name]`
+3. Recipient processes inbox and sends completion to sender
+
+**Critical:** EM does NOT use Task tool to invoke agents (loses MCP access).
+
+## Quick Commands
+
+```bash
+# Add a new agent
+./coreai/scripts/add-agent.sh <agent-name> --type ic
+
+# Invoke an agent
+@engineering-manager /delegate SUR-XX to backend-engineer
+@backend-engineer /check-inbox
+```
+
+## Code Development Guidelines
+
+### Core Philosophy
+- Favor simplicity over cleverness
+- Start minimal and iterate
+- Optimize for the next developer
+
+### Quality Checklist
+- [ ] Can a new team member understand this code in 5 minutes?
+- [ ] Are variable and function names self-explanatory?
+- [ ] Is the happy path clear and error handling robust?
+- [ ] Could this be simpler without losing functionality?
+
+### Red Flags
+- Functions longer than 20-30 lines
+- More than 3 levels of nesting
+- Variable names like `data`, `item`, `temp`
+- Abstractions only used once

package/templates/project-files/coreai.json.example

@@ -0,0 +1,47 @@
+{
+  "project": {
+    "name": "My Project",
+    "jiraProject": "PROJ",
+    "githubRepo": "owner/repo",
+    "confluenceSpace": "PROJ",
+    "confluenceUrl": "https://yourcompany.atlassian.net/wiki",
+    "jiraUrl": "https://yourcompany.atlassian.net"
+  },
+  "agents": {
+    "installed": [
+      "engineering-manager",
+      "backend-engineer",
+      "frontend-engineer",
+      "qa-engineer"
+    ],
+    "custom": []
+  },
+  "commands": {
+    "core": [
+      "delegate",
+      "check-inbox",
+      "review",
+      "sprint-status",
+      "git-commit",
+      "pr-create"
+    ],
+    "optional": [
+      "jira-create",
+      "jira-transition",
+      "worktree-setup",
+      "worktree-cleanup",
+      "docs-update"
+    ]
+  },
+  "qualityChecks": {
+    "lint": "./gradlew ktlintCheck",
+    "staticAnalysis": "./gradlew detekt",
+    "test": "./gradlew testDebugUnitTest",
+    "build": "./gradlew assembleDebug"
+  },
+  "techStack": {
+    "language": "kotlin",
+    "framework": "android",
+    "notes": "Customize qualityChecks for your tech stack"
+  }
+}

package/templates/project-files/mcp.json.template

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    "atlassian": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-atlassian"],
+      "env": {
+        "ATLASSIAN_HOST": "${ATLASSIAN_HOST}",
+        "ATLASSIAN_EMAIL": "${ATLASSIAN_EMAIL}",
+        "ATLASSIAN_API_TOKEN": "${ATLASSIAN_API_TOKEN}"
+      }
+    }
+  }
+}

package/templates/review-complete.md

@@ -0,0 +1,64 @@
+# Review Complete Template
+
+**Usage:** Reviewer reports review completion to EM
+
+**Filename:** `YYYYMMDD_HHMM-[agent-name]-PR-XX-review.md`
+
+**Location:** `/KnowledgeLibrary/engineering-manager/inbox/`
+
+---
+
+```markdown
+---
+type: completion-report
+from: [agent-name]
+to: engineering-manager
+date: [YYYY-MM-DD HH:MM]
+ticket: SUR-XX
+priority: P1
+---
+
+## Review Complete: PR #XX - SUR-XX
+
+### Decision
+**APPROVED** | **CHANGES REQUESTED**
+
+### Summary
+[What was reviewed and key findings]
+
+### Review Posted
+- GitHub PR comment posted: Yes
+- Decision clearly stated in comment
+
+### Key Findings
+- [Finding 1]
+- [Finding 2]
+
+### [If CHANGES REQUESTED]
+Issues to address:
+1. [Issue 1]
+2. [Issue 2]
+
+---
+
+## Workflow Checkpoint
+
+**Workflow:** Code Review
+**Ticket:** SUR-XX
+**Previous State:** REVIEWING
+**Current State:** DECISION_POSTED
+**Timestamp:** [YYYY-MM-DD HH:MM]
+
+### Entry Conditions Verified
+- [x] PR exists and CI passing
+- [x] Review request received via inbox
+
+### Required Outputs Completed
+- [x] Review posted on GitHub PR via `gh pr comment`
+- [x] Decision stated: [APPROVED/CHANGES_REQUESTED]
+- [x] Completion report sent to EM inbox
+
+### Next State
+**Target:** [APPROVED state if approved, or back to engineer]
+**Blockers:** None
+```

package/templates/review-request.md

@@ -0,0 +1,67 @@
+# Review Request Template
+
+**Usage:** EM requests PR review from specialist
+
+**Filename:** `YYYYMMDD_HHMM-engineering-manager-review-PR-XX.md`
+
+**Location:** `/KnowledgeLibrary/[reviewer-agent]/inbox/`
+
+---
+
+```markdown
+---
+type: review-request
+from: engineering-manager
+to: [agent-name]
+date: [YYYY-MM-DD HH:MM]
+ticket: SUR-XX
+priority: P1
+---
+
+## PR Review Request
+
+**PR:** #[number] - [title]
+**URL:** https://github.com/[owner]/[repo]/pull/[number]
+**Ticket:** SUR-XX
+**Author:** [author-agent]
+
+### Review Focus
+[Based on reviewer's role:]
+- solutions-architect: Architecture alignment, patterns, design
+- security-engineer: Security vulnerabilities, data handling
+- qa-engineer: Test coverage, edge cases
+
+### Requirements
+
+1. Review the PR thoroughly
+2. **Post review as GitHub PR comment** using `gh pr comment`
+3. Use the standard review format (see below)
+4. State APPROVED or CHANGES_REQUESTED
+5. Send completion summary to my inbox
+
+### Review Comment Format
+
+```
+## [Review Type]: SUR-XX
+
+### Summary
+[What was reviewed]
+
+### Checklist
+- [x] [Check relevant to your role]
+- [x] [Check relevant to your role]
+
+### Findings
+- [Findings]
+
+### **DECISION: APPROVED** | **DECISION: CHANGES REQUESTED**
+
+[Explanation]
+
+---
+*Review by: [agent-name]*
+```
+
+### References
+- Jira: https://[site].atlassian.net/browse/SUR-XX
+```