contextos-agents 2.1.1 → 2.3.0

package/.agents/compiler/manifest-compiler.js

@@ -655,34 +655,10 @@ class ManifestCompiler {
   compile() {
     this.diagnostics = [];
     const manifestsById = {};
-    const skillDirs = [];
-
-    // 1. Discover skill directories
-    if (fs.existsSync(this.coreSkillsDir)) {
-      const entries = fs.readdirSync(this.coreSkillsDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.isDirectory()) {
-          skillDirs.push(path.join(this.coreSkillsDir, entry.name));
-        }
-      }
-    }
-
-    // Also check plugins
-    const pluginsDir = path.join(this.agentsDir, 'plugins');
-    if (fs.existsSync(pluginsDir)) {
-      const pluginEntries = fs.readdirSync(pluginsDir, { withFileTypes: true });
-      for (const pe of pluginEntries) {
-        if (pe.isDirectory()) {
-          const pSkills = path.join(pluginsDir, pe.name, 'skills');
-          if (fs.existsSync(pSkills)) {
-            const subs = fs.readdirSync(pSkills, { withFileTypes: true });
-            for (const sub of subs) {
-              if (sub.isDirectory()) skillDirs.push(path.join(pSkills, sub.name));
-            }
-          }
-        }
-      }
-    }
+    const skillDirs = require('../plugins.js').collectAllSkillDirs(path.dirname(this.agentsDir), {
+      coreSkillsDir: this.coreSkillsDir,
+      agentsDir: this.agentsDir,
+    });
 
     // Sort skill directories for determinism
     skillDirs.sort();
@@ -697,7 +673,7 @@ class ManifestCompiler {
         // Synthesize minimal manifest from directory name & SKILL.md
         const id = path.basename(dir);
         const norm = this.normalizeManifest(dir, `id: ${id}\nname: ${id}\n`);
-        norm.source = path.relative(this.rootDir, dir).replace(/\\/g, '/');
+        norm.source = path.relative(this.rootDir, path.join(dir, norm.entrypoint)).replace(/\\/g, '/');
         manifestsById[id] = norm;
         continue;
       }

package/.agents/core/skills/context-os/references/project-graph.md

@@ -28,7 +28,7 @@ The Project Graph lives in `docs/PROJECT_GRAPH.md` and follows this format:
 project:
   name: "DentalCRM"
   type: crm
-  
+
 modules:
   patients:
     description: "Patient management"
@@ -40,7 +40,7 @@ modules:
       - src/modules/patients/**
     skills: [react, typescript, postgres]
     depends_on: [auth]
-    
+
   appointments:
     description: "Appointment scheduling"
     features:
@@ -51,7 +51,7 @@ modules:
       - src/modules/appointments/**
     skills: [react, typescript, postgres]
     depends_on: [patients, auth]
-    
+
   auth:
     description: "Authentication and authorization"
     features:

package/.agents/core/skills/engineering-workflow/SKILL.md

@@ -1,343 +1,38 @@
 ---
 name: engineering-workflow
-description: >
-  Senior engineering workflow skill. Enforces spec → plan → build → test → review → ship.
-  AI never writes code before a spec and plan are approved. Acts like a senior, not a junior.
-  Integrated with gstack-roles for automatic role activation per phase.
+description: Scope implementation work, verify behavior, and report evidence using a proportional lifecycle.
 ---
 
 # engineering-workflow
 
 ## Overview
 
-Systematic 6-phase engineering pipeline (DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP) enforcing role declarations, atomic task execution, quality gates, regression prevention, and structured requirements elicitation.
+Define the outcome, plan substantial changes, implement, verify, review, and report. Existing user authorization carries forward.
 
 ## When to Use
 
-Activate on all project tasks to orchestrate structured development, spec definition, architectural planning, and verification gates.
+Implementation, debugging, reviews, and release preparation. Routine maintenance and diagnostics can proceed directly with relevant checks.
 
 ## Rules & Patterns
 
-Inspired by [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) by Addy Osmani (Google Chrome) and [obra/superpowers](https://github.com/obra/superpowers).
+Establish acceptance criteria for substantial or ambiguous features. Ask only for missing decisions that affect scope or safety. An explicit implementation request authorizes ordinary reversible work. Preserve unrelated changes. Verify behavior before reporting completion. Publishing and external messages need authorization for that action.
 
-### Core Principle
-
-> **A junior writes code immediately. A senior writes a spec first.**  
-> You are a senior. You never write code until the spec and plan are approved.
-
----
-
-### The 6-Phase Development Pipeline
-
-```
-  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
- ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
- │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
- │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
- └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
-   /spec          /plan          /build        /test         /review       /ship
-
-[ROLE: Product Manager]  [ROLE: Architect]  [ROLE: Senior Dev]  [ROLE: QA Lead]  [ROLE: Staff Eng]  [ROLE: Release Eng]
-```
-
-**IRON RULE**: In interactive development, no phase can be skipped and no code is written before `/plan` is approved.  
-**Direct Build & Fast-Track Exception**: When the prompt/caller explicitly requests a standalone implementation, declares `[PHASE: Build]`, or requests routine operational/maintenance tasks (git operations, version bumps, typo fixes, small config tweaks, diagnostic checks), proceed directly to execution without conversational approval pauses.
-
----
-
-### Phase 1: DEFINE - /spec
-
-**Auto-activates → `[ROLE: Product Manager]`**
-
-Turn vague intent into a precise, executable specification.
-
-#### Step 1.1: The Interview Protocol (`interview-me`)
-
-Before writing the spec, if there is ambiguity, high blast radius, or multiple architectural paths, stop and ask the user **one question at a time** (or up to 2 tightly coupled questions):
-
-1. **Clarify Business Intent**: What user problem are we solving? What is explicitly out of scope?
-2. **Clarify Constraints**: Runtime versions, database engines, performance bounds.
-3. **Clarify Edge Cases**: What happens on offline state, empty lists, unauthorized requests?
-
-#### Step 1.2: Spec Template
-
-```markdown
-## Feature Spec: [Feature Name]
-
-### Why (Problem)
-[What pain does this solve? Who has it? How often?]
-
-### Scope (What's In / Out)
-
-**In-Scope**:
-- [Specific item 1]
-- [Specific item 2]
-
-**Out-of-Scope**:
-- [Thing we're NOT doing and why]
-
-### Technical Approach
-[Read the relevant code. Understand what changes where.]
-Files affected:
-- `src/X.js` - [what changes]
-- `src/Y.js` - [what changes]
-
-### Acceptance Criteria
-- [ ] Given [context], when [action], then [result]
-- [ ] Given [context], when [action], then [result]
-
-### Open Questions
-- [Unresolved decision 1]
-- [Unresolved decision 2]
-```
-
----
-
-### Phase 2: PLAN - /plan
-
-**Auto-activates → `[ROLE: Architect]`**
-
-Break the spec into atomic, independently testable tasks.
-
-#### Thin Vertical Slices (`incremental-implementation`)
-
-Organize tasks as **Thin Vertical Slices** rather than horizontal layers:
-
-- **Bad (Horizontal)**: Task 1: All DB migrations. Task 2: All API routes. Task 3: All UI components. (Nothing works until step 3).
-- **Good (Vertical Slices)**: Slice 1: Minimal DB table + minimal API + minimal UI button end-to-end. Verify and commit. Slice 2: Add validation + edge cases. Slice 3: Polish UI & telemetry.
-
-#### Plan Rules
-
-- Each task must be **completable in < 2 hours** of focused work.
-- Each task must be **independently testable**.
-- Tasks must be **ordered by dependency** (blocking tasks first).
-- Each task gets a **test requirement** - no task without a test.
-
-#### Plan Template
-
-```markdown
-## Implementation Plan: [Feature Name]
-
-### Tasks
-
-**Task 1: [Slice 1 Name]** (est. 30min)
-- What: [Specific implementation detail]
-- Files: [file1.js, file2.js]  
-- Test: [How will you verify this works?]
-- Blocked by: [nothing / Task N]
-
-**Task 2: [Slice 2 Name]** (est. 45min)
-- What: [Specific implementation detail]
-- Files: [file3.js]
-- Test: [Test description]
-- Blocked by: Task 1
-
-### Risk Assessment
-- [Risk 1]: [Mitigation]
-- [Risk 2]: [Mitigation]
-
-### STOP - Awaiting Approval
-Do not proceed to BUILD until this plan is approved.
-```
-
----
-
-### Phase 3: BUILD - /build
-
-**Auto-activates → `[ROLE: Senior Developer]`**
-
-Implement one task at a time. Commit after each task.
-
-#### Build Rules
-
-1. **One task per commit** - atomic, descriptive commit messages.
-2. **Write the test FIRST** (TDD - red-green-refactor).
-3. **No dead code** - if it's not tested, it's not shipped.
-4. **No TODOs in committed code** - resolve or create a tracked issue.
-5. **Read before writing** - understand the surrounding code before changing it.
-6. **Limit the blast radius** - modify ONLY the files explicitly listed in the current task's plan. Do NOT rewrite adjacent components, hooks, or utilities unless strictly required AND approved.
-
-#### Commit Message Format
-
-```text
-type(scope): short description (max 72 chars)
-
-- Detail 1
-- Detail 2
-
-Refs: #issue-number
-```
-
-Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
-
----
-
-### Phase 4: VERIFY - /test
-
-**Auto-activates → `[ROLE: QA Lead]`**
-
-Tests are proof, not an afterthought.
-
-#### Test Strategy by Code Type
-
-**Logic & Services (TDD)**:
-
-```text
-1. RED:      Write a failing test for the next small behavior
-2. GREEN:    Write the minimum code to make it pass
-3. REFACTOR: Clean up without breaking tests
-4. REPEAT
-```
-
-**UI Components & User Flows (BDD)**:
-
-For complex React components, prioritize testing _user behavior_ over internal state:
-
-- Use **React Testing Library** (`userEvent`, `screen.getByRole`) - test what the user sees.
-- Use **Playwright** for critical user flows (login, checkout, form submit).
-- Do NOT test implementation details (internal state, private methods, component structure).
-- Focus on: "When user clicks X, does Y appear?" not "Does `useState` hold the right value?"
-
-```tsx
-// [GOOD] BDD: Test behavior
-test("shows error when email is invalid", async () => {
-  render(<LoginForm />);
-  await userEvent.type(screen.getByLabelText("Email"), "not-an-email");
-  await userEvent.click(screen.getByRole("button", { name: /sign in/i }));
-  expect(screen.getByText(/invalid email/i)).toBeInTheDocument();
-});
-```
-
-#### Test Quality Gates
-
-Before moving to Review, verify:
-
-- [ ] All new code has tests
-- [ ] Tests are meaningful (not just coverage theater)
-- [ ] Edge cases are covered (null, empty, overflow, unauthorized)
-- [ ] Tests fail when the implementation is broken (anti-regression)
-- [ ] Test names are readable: `it("returns 404 when user not found")`
-
----
-
-### Phase 5: REVIEW - /review
-
-**Auto-activates → `[ROLE: Staff Engineer]` + `[ROLE: Senior Designer]` for UI tasks**
-
-Review before merging. Always.
-
-#### Subagent / Peer Code Review Protocol
-
-Inspired by [obra/superpowers](https://github.com/obra/superpowers):
-
-1. **Self-Review First**: The implementer runs git diff and verifies against the original acceptance criteria.
-2. **Review Checklist**:
-   - **Correctness**: Does it do what the spec says? Are all criteria met?
-   - **Architecture**: Single Responsibility, DRY without premature abstraction, no business logic in API routes.
-   - **Security**: No secrets hardcoded, inputs validated via Zod/schemas, auth checked before data access.
-   - **Performance**: No N+1 queries, expensive operations cached, sets paginated.
-   - **Design**: If UI, passes `impeccable-design` quick audit (typography, colors, spacing, animations).
-
----
-
-### Phase 5.5: SIMPLIFY - /simplify
-
-**Auto-activates → `[ROLE: Staff Engineer]` (Ponytail Mindset)**
-
-Before merging, ruthlessly simplify:
-
-1. Did we introduce abstractions that are only used once? (Inline them).
-2. Can 3 lines of standard JavaScript replace a 50-line custom utility?
-3. Is any configuration or generic handler premature? (YAGNI).
-4. Is the code obvious to a mid-level engineer without reading a documentation manual?
-
----
-
-### Phase 6: SHIP - /ship
-
-**Auto-activates → `[ROLE: Release Engineer]`**
-
-Only ship when all gates are green.
-
-#### Pre-Ship Checklist
-
-- [ ] All tests pass in CI
-- [ ] No lint errors
-- [ ] Feature works in staging environment
-- [ ] Docs updated (README, API docs, changelogs)
-- [ ] Breaking changes documented
-- [ ] Rollback plan exists
-- [ ] Preview / staging deployment verified (if applicable, e.g. Vercel Preview and Core Web Vitals for frontend deployments)
-
-#### Operational Self-Improvement
-
-Before completing a workflow, review the session for durable learnings. Write them to `.agents/learnings.md`. If no durable learning occurred, state "No durable learnings this session" in your final output.
-
----
+Read [references/workflow.md](references/workflow.md) for detailed procedures and examples only when needed.
 
 ## Code Examples
 
-### Vertical Slice Example
-
-```javascript
-// Slice 1: Minimal functional endpoint
-// POST /api/v1/projects -> creates project with basic validation
-import { z } from 'zod';
-import { projectService } from '@/services/project';
-
-const CreateProjectSchema = z.object({
-  name: z.string().min(1).max(100),
-  description: z.string().optional()
-});
-
-export async function POST(req) {
-  const session = await auth();
-  if (!session?.userId) return Response.json({ error: 'Unauthorized' }, { status: 401 });
-
-  const body = await req.json();
-  const parsed = CreateProjectSchema.parse(body);
-  const project = await projectService.create({ ...parsed, userId: session.userId });
-
-  return Response.json(project, { status: 201 });
-}
-```
-
----
+A README typo needs an edit and relevant formatting check. An authentication feature needs access boundaries, failure cases, implementation, and behavioral verification.
 
 ## Validation Checklist
 
-- [ ] Specification exists with clear In-Scope and Out-of-Scope boundaries.
-- [ ] Implementation plan broken down into vertical tasks < 2 hours each.
-- [ ] Tests written before implementation (TDD/BDD).
-- [ ] Code reviewed against correctness, security, performance, and design gates.
-- [ ] Staged security and quality check passes (`contextos scan --staged --enforce`).
-- [ ] Simplification ladder executed before shipping.
-
----
+- [ ] The requested outcome is handled.
+- [ ] Relevant verification and safety boundaries are preserved.
+- [ ] Limitations are stated.
 
 ## Common Mistakes
 
-- **Writing code before approval**: Skipping `/spec` or `/plan` in interactive sessions.
-- **Horizontal task splitting**: Building all DB models first without verifying end-to-end integration.
-- **Premature refactoring**: Changing unrelated adjacent code during a feature task.
-- **Ignoring non-happy paths**: Testing only 200 OK responses while ignoring 400, 401, 404, 500 scenarios.
-
----
+Repeated approval after authorization; unnecessary ceremonies for routine edits; treating role labels or string checks as behavioral proof.
 
 ## Integration Notes
 
-- Integrates with `gstack-roles` for automated role switching across all 6 phases.
-- Triggers `ponytail-mindset` during the BUILD and SIMPLIFY phases.
-- Hands off to `impeccable-design` for UI quality review.
-- Coordinates with `security` during Phase 5 for pre-merge compliance.
-
----
-
-## Completion Status Protocol
-
-When completing a task or workflow, you must explicitly report your final status as the last part of your output:
-
-- **DONE** - completed with evidence.
-- **DONE_WITH_CONCERNS** - completed, but list concerns.
-- **BLOCKED** - cannot proceed; state blocker and what was tried.
-- **NEEDS_CONTEXT** - missing info; state exactly what is needed.
+Load relevant domain skills and supporting resources on demand. Compatibility identifiers remain available.