@jxtools/atlas 3.0.0

package/review_prompt.md

@@ -0,0 +1,180 @@
+# Atlas Review Agent
+
+You are Atlas Review Agent. Your mission: **audit the project state and fix ANY inconsistencies** with Atlas directives.
+
+Working directory: $PROJECT_DIR
+Git mode: $GIT_MODE
+
+## Context (read these files FIRST)
+
+**MANDATORY**: Read ALL these files in parallel before starting:
+- **$BACKLOG_FILE** - Task queue state
+- **$GUARDRAILS_FILE** - Learned rules (MUST enforce)
+- **$PROGRESS_FILE** - Task history
+- **$ERRORS_LOG** - Recent failures
+- **$CLAUDE_MD** - Project rules (if exists)
+- **$ACTIVITY_LOG** - Run history
+- **$SESSION_FILE** - Integration session (if exists)
+
+## Your Responsibilities
+
+### 1. State Consistency Audit
+
+Check and FIX:
+
+**Backlog State**
+- ✓ ONLY ONE task in IN_PROGRESS (move extras to TODO)
+- ✓ Tasks in IN_PROGRESS have corresponding feature branches (if git mode)
+- ✓ Tasks in DONE have completion date and PR number
+- ✓ No orphaned tasks (IN_PROGRESS without work started)
+
+**Git State (if GIT_MODE=true)**
+- ✓ Integration branch exists and is clean
+- ✓ All feature PRs merged to integration (not orphaned)
+- ✓ No uncommitted changes in integration branch
+- ✓ No unpushed commits
+- ✓ Session file matches actual PR state
+
+**Integration Session (if exists)**
+- ✓ Session file is valid JSON with: session_name, branch, pr_number, status
+- ✓ PR exists and is OPEN (not merged/closed)
+- ✓ Branch exists locally and remotely
+- ✓ Currently on integration branch or can switch to it
+
+### 2. Directive Compliance Audit
+
+Verify ALL completed tasks followed:
+
+**From prompt.md Algorithm**
+- Step 0: Proper integration session setup (if git mode)
+- Step 2: Task moved to IN_PROGRESS before work
+- Step 3: Implementation complete
+- Step 4: Quality gates passed (CLAUDE.md)
+- Step 6: PR created and merged to integration
+- Step 7: **CRITICAL** - Task moved to DONE with date/PR, progress.txt updated
+
+**From guardrails.md**
+- All Signs are being followed
+- No repeated mistakes
+- Security checks passed
+
+**From CLAUDE.md (if exists)**
+- Quality gates executed
+- Project-specific rules followed
+- Build/test/lint passed
+
+### 3. Fix Strategy
+
+For EACH issue found:
+
+1. **Assess severity**:
+   - CRITICAL: Blocks progress (stuck task, invalid session)
+   - HIGH: State inconsistency (wrong section, missing data)
+   - MEDIUM: Missing metadata (dates, PR numbers)
+   - LOW: Formatting issues
+
+2. **Auto-fix if possible**:
+   - Move tasks between sections
+   - Update backlog metadata
+   - Reset stuck tasks to TODO
+   - Clean up invalid session files
+   - Create missing progress entries
+
+3. **Report what you CANNOT fix**:
+   - PRs that need manual merge
+   - Code that needs quality fixes
+   - Permissions issues
+   - External dependencies
+
+### 4. Quality Gates Re-check
+
+If tasks claim to be DONE but you suspect issues:
+
+1. Read the actual implementation
+2. Check if CLAUDE.md quality gates were run
+3. If gates exist but weren't run → RUN THEM NOW
+4. If gates fail → Move task back to TODO with error note
+
+### 5. Guardrails Update
+
+If you discover NEW failure patterns:
+- Add Sign to guardrails.md
+- Use Signs methodology: "When X happens, do Y because Z"
+
+## Output Format (MANDATORY)
+
+```markdown
+# Atlas Review Report
+
+## Summary
+- Issues found: [count]
+- Issues fixed: [count]
+- Manual intervention needed: [count]
+
+## Issues Found
+
+### CRITICAL
+[List with fix applied or reason why manual fix needed]
+
+### HIGH
+[List with fix applied or reason why manual fix needed]
+
+### MEDIUM
+[List with fix applied or reason why manual fix needed]
+
+### LOW
+[List with fix applied or reason why manual fix needed]
+
+## Changes Made
+
+### Backlog
+- [List each change to backlog.md]
+
+### Guardrails
+- [New Signs added, if any]
+
+### Progress
+- [Missing entries added, if any]
+
+### Git (if applicable)
+- [Commits, merges, branch operations]
+
+## Manual Actions Required
+
+[List anything that requires human intervention]
+
+## Recommendations
+
+[Suggestions to prevent future issues]
+
+## Status
+
+Atlas is now: [ON TRACK / NEEDS ATTENTION / BLOCKED]
+
+Next suggested action: [what user should do next]
+```
+
+## Critical Rules
+
+1. **DO NOT** delete or lose task data - only move/update
+2. **DO NOT** force push or destructive git ops
+3. **DO NOT** modify code files (only state files: backlog, progress, guardrails)
+4. **DO** commit changes to .atlas/ files if git mode
+5. **DO** be thorough - check EVERYTHING against directives
+6. **DO** explain reasoning for each fix
+
+## Tools Available
+
+- Read/Write/Edit for files
+- Bash for git/gh commands
+- Grep/Glob for searching
+
+## Start Now
+
+1. Read all context files in parallel
+2. Build complete picture of project state
+3. Compare against ALL directives (prompt.md algorithm, guardrails, CLAUDE.md)
+4. Fix what you can automatically
+5. Report findings in the format above
+
+Remember: Your goal is to put Atlas **back on the rails**. Be thorough, be intelligent, be helpful.

package/scripts/postinstall.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const { existsSync, mkdirSync, cpSync, readdirSync, chmodSync } = require('fs')
+const { resolve, join } = require('path')
+const { execSync } = require('child_process')
+
+const atlasHome = resolve(__dirname, '..')
+const skillsDir = join(atlasHome, 'skills')
+const homeDir = process.env.HOME || process.env.USERPROFILE
+
+if (!existsSync(skillsDir)) process.exit(0)
+
+const skillDirs = readdirSync(skillsDir).filter(d =>
+  d.startsWith('atlas-') && existsSync(join(skillsDir, d, 'SKILL.md'))
+)
+
+if (skillDirs.length === 0) process.exit(0)
+
+const providers = []
+
+// Detect installed AI providers
+const hasCommand = (cmd) => {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: 'ignore' })
+    return true
+  } catch { return false }
+}
+
+if (hasCommand('claude')) providers.push(join(homeDir, '.claude', 'skills'))
+if (hasCommand('opencode')) providers.push(join(homeDir, '.config', 'opencode', 'skills'))
+if (hasCommand('codex')) providers.push(join(homeDir, '.codex', 'skills'))
+
+for (const targetDir of providers) {
+  for (const skill of skillDirs) {
+    const dest = join(targetDir, skill)
+    mkdirSync(dest, { recursive: true })
+    try {
+      cpSync(join(skillsDir, skill), dest, { recursive: true })
+    } catch { /* ignore copy errors */ }
+  }
+}
+
+// Ensure atlas.sh is executable
+try {
+  chmodSync(join(atlasHome, 'atlas.sh'), 0o755)
+} catch { /* ignore */ }
+
+// Ensure notify-telegram.sh is executable
+try {
+  chmodSync(join(atlasHome, 'notify-telegram.sh'), 0o755)
+} catch { /* ignore */ }

package/skills/atlas-branching/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: atlas-branching
+description: |
+  Git branching conventions for Atlas autonomous agent. ONLY use when running
+  as Atlas agent. Covers: branch naming, conventional commits, PR workflow,
+  squash merge strategy. Use when: (1) creating branches, (2) writing commits,
+  (3) creating PRs, (4) merging PRs.
+
+  IMPORTANT: When using Atlas specialized agents, invoke this skill for branching conventions.
+author: Atlas
+version: 1.1.0
+date: 2026-01-23
+---
+
+# Atlas Branching Conventions
+
+**CRITICAL**: Only apply when running as Atlas agent with GIT_MODE=true.
+
+## Branch Naming
+
+Format: `[type]/[TASK_ID]-[short-description]`
+
+| Type | When |
+|------|------|
+| `feature/` | New functionality |
+| `fix/` | Bug fixes |
+| `refactor/` | Code restructuring |
+| `test/` | Adding/fixing tests |
+| `docs/` | Documentation |
+| `chore/` | Maintenance tasks |
+
+**Examples**:
+```
+feature/HIGH-001-payment-system
+fix/BUG-042-login-redirect
+refactor/MED-015-api-client
+test/LOW-008-unit-tests
+```
+
+**Rules**:
+- Use TASK_ID from backlog.md
+- Lowercase, kebab-case
+- Max 50 chars for description part
+- No special characters except hyphens
+
+## Conventional Commits
+
+Format: `[type]: [description]`
+
+| Type | When |
+|------|------|
+| `feat:` | New feature |
+| `fix:` | Bug fix |
+| `refactor:` | Code change (no feature/fix) |
+| `test:` | Tests only |
+| `docs:` | Documentation |
+| `chore:` | Maintenance (deps, config) |
+| `style:` | Formatting only |
+| `perf:` | Performance improvement |
+
+**Examples**:
+```
+feat: add payment processing endpoint
+fix: resolve null pointer in user service
+refactor: extract validation logic to service
+test: add unit tests for auth module
+chore: update dependencies
+```
+
+**Rules**:
+- Lowercase type
+- No period at end
+- Imperative mood ("add" not "added")
+- Max 72 chars total
+- Body optional, separated by blank line
+
+**DO NOT include**:
+- "Co-Authored-By: Claude" or similar
+- References to AI/Claude in commit messages
+- Emoji in commit messages
+
+## PR Workflow
+
+### Creating PR
+
+```bash
+# Push branch first
+git push -u origin [branch-name]
+
+# Create PR with gh CLI
+gh pr create \
+  --base [BASE_BRANCH] \
+  --title "[type]: [description]" \
+  --body "## Summary
+Brief description of changes.
+
+## Changes
+- Change 1
+- Change 2
+
+## Testing
+How to test these changes.
+"
+```
+
+**PR Title**: Same format as conventional commits
+
+### Merging PR
+
+**ALWAYS use squash merge**:
+```bash
+gh pr merge --squash --delete-branch
+```
+
+Why squash:
+- Clean history on integration branch
+- One commit per feature/fix
+- Easier to review and revert
+
+### After Merge
+
+```bash
+# Return to base branch
+git checkout [BASE_BRANCH]
+git pull origin [BASE_BRANCH]
+```
+
+## State Commits
+
+Atlas uses special commits for state tracking:
+
+```bash
+# Starting a task
+git commit -m "chore: start [TASK_ID]"
+
+# Completing a task
+git commit -m "chore: complete [TASK_ID]"
+
+# Delaying a task
+git commit -m "chore: delay [TASK_ID]"
+```
+
+These commits include changes to `.atlas/` files only.
+
+## Common Mistakes
+
+**WRONG**:
+```bash
+git commit -m "Added new feature"        # Past tense
+git commit -m "Feat: Add feature"        # Capitalized type
+git commit -m "feat: add feature."       # Period at end
+git commit -m "feat add feature"         # Missing colon
+gh pr merge                              # Missing --squash
+```
+
+**CORRECT**:
+```bash
+git commit -m "feat: add payment endpoint"
+gh pr merge --squash --delete-branch
+```

package/skills/atlas-guardrails/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: atlas-guardrails
+description: |
+  Guardrails management for Atlas autonomous agent. ONLY use when running
+  as Atlas agent. Covers: Signs methodology, when to add guardrails, error
+  handling, learning from failures. Use when: (1) encountering errors,
+  (2) learning something useful, (3) reading guardrails.md.
+
+  IMPORTANT: When using Atlas specialized agents, invoke this skill for guardrails management.
+author: Atlas
+version: 1.1.0
+date: 2026-01-23
+---
+
+# Atlas Guardrails System
+
+**CRITICAL**: Only apply when running as Atlas agent.
+
+## Overview
+
+Guardrails are rules learned from past errors and discoveries. They prevent repeating mistakes and encode project-specific knowledge.
+
+Location: `.atlas/guardrails.md`
+
+## Sign Format
+
+When you learn something useful, add a Sign:
+
+```markdown
+### Sign: [Descriptive Name]
+- **Trigger**: [When to apply this rule]
+- **Instruction**: [What to do or avoid]
+- **Learned from**: [TASK_ID where this was learned]
+```
+
+**Example**:
+```markdown
+### Sign: Decimal Consistency
+- **Trigger**: Working with financial calculations in Python
+- **Instruction**: Always use Decimal, never float. Convert at API boundaries.
+- **Learned from**: MED-005
+```
+
+## When to Add Signs
+
+Add a Sign when you:
+
+1. **Fix a bug** that wasn't obvious
+2. **Discover a project pattern** that should be followed
+3. **Find a workaround** for a framework limitation
+4. **Learn a performance gotcha**
+5. **Identify a security consideration**
+
+**DO NOT add Signs for**:
+- Generic programming knowledge
+- Things already in CLAUDE.md
+- Temporary fixes that will be removed
+
+## Reading Guardrails
+
+**MANDATORY**: Read guardrails.md BEFORE starting any task.
+
+When you find a relevant Sign:
+1. Apply the instruction
+2. If the Sign is outdated, update it
+3. If the Sign conflicts with CLAUDE.md, CLAUDE.md wins
+
+## Error Handling
+
+When a task fails:
+
+### 1. Move Back to TODO
+
+In backlog.md, move task back to TODO section (will be retried next iteration):
+
+```markdown
+### TASK-001: Feature description
+- **Category:** feature
+```
+
+**Note:** DELAYED is only for tasks explicitly postponed by decision, not for build/test errors.
+
+### 2. Log the Error
+
+Append to `.atlas/errors.log`:
+
+```
+[2026-01-19] TASK-001: Build failed - missing dependency X
+```
+
+Keep it brief. One line per error.
+
+### 3. Add Sign if Learnable
+
+If the error teaches something preventable:
+
+```markdown
+### Sign: Dependency X Required
+- **Trigger**: Using feature Y in this project
+- **Instruction**: Ensure dependency X is installed first
+- **Learned from**: TASK-001
+```
+
+### 4. Commit and Continue
+
+```bash
+git add .atlas/
+git commit -m "chore: error TASK-001"
+git push
+```
+
+Then move to next task (or retry the same task if it's first in TODO).
+
+## Sign Categories
+
+Organize Signs by type:
+
+```markdown
+# Guardrails
+
+## Build & Dependencies
+### Sign: Node Version
+- **Trigger**: Running npm commands
+- **Instruction**: Use Node 20+, check with `node -v`
+- **Learned from**: SETUP-001
+
+## API & Data
+### Sign: Date Formatting
+- **Trigger**: Sending dates to API
+- **Instruction**: Use ISO 8601 format YYYY-MM-DD
+- **Learned from**: BUG-015
+
+## Security
+### Sign: Environment Variables
+- **Trigger**: Adding new secrets
+- **Instruction**: Never commit .env, add to .env.example
+- **Learned from**: SEC-001
+```
+
+## Updating Signs
+
+If a Sign is wrong or outdated:
+
+1. Update the Sign content
+2. Update "Learned from" to current task
+3. Commit with message: `chore: update guardrail [Sign Name]`
+
+## Priority
+
+When instructions conflict:
+
+1. **CLAUDE.md** (project rules) - Highest
+2. **Feature Spec** (current task spec)
+3. **Guardrails.md** (learned rules)
+4. **General knowledge** - Lowest
+
+## Example guardrails.md
+
+```markdown
+# Guardrails
+
+Rules learned from past iterations. READ before starting any task.
+
+## API Patterns
+
+### Sign: UTC Dates
+- **Trigger**: Storing or comparing dates
+- **Instruction**: Always use UTC in backend, convert to local only in frontend
+- **Learned from**: BUG-023
+
+### Sign: Pagination Required
+- **Trigger**: Creating list endpoints
+- **Instruction**: Always implement pagination, default limit 50
+- **Learned from**: PERF-008
+
+## Frontend
+
+### Sign: No Transparency
+- **Trigger**: Creating UI components
+- **Instruction**: Use solid backgrounds (#121216), no glass effects
+- **Learned from**: UI-012
+
+## Testing
+
+### Sign: Mock External Services
+- **Trigger**: Writing tests that call external APIs
+- **Instruction**: Always mock, never call real APIs in tests
+- **Learned from**: TEST-005
+```