@jxtools/atlas 3.0.0

package/notify-telegram.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# Atlas -> Telegram Notification Script
+#
+# Configure via environment variables:
+#   ATLAS_TELEGRAM_BOT  - Telegram bot token
+#   ATLAS_TELEGRAM_CHAT - Chat/group ID
+#
+# To disable: export ATLAS_NOTIFY_TELEGRAM=false
+
+BOT_TOKEN="${ATLAS_TELEGRAM_BOT:-}"
+CHAT_ID="${ATLAS_TELEGRAM_CHAT:-}"
+
+# Exit silently if not configured
+if [[ -z "$BOT_TOKEN" ]] || [[ -z "$CHAT_ID" ]]; then
+    exit 0
+fi
+
+ITERATION="$1"
+MAX_ITERATIONS="$2"
+PROJECT_NAME="$3"
+SUMMARY="$4"
+
+# Progress bar
+progress_bar() {
+    local current=$1
+    local max=$2
+    [[ $max -le 0 ]] && max=1
+    local filled=$((current * 10 / max))
+    local empty=$((10 - filled))
+    local bar=""
+    for ((i=0; i<filled; i++)); do bar+="█"; done
+    for ((i=0; i<empty; i++)); do bar+="░"; done
+    echo "$bar"
+}
+
+PROGRESS=$(progress_bar "$ITERATION" "$MAX_ITERATIONS")
+TIMESTAMP=$(date "+%H:%M")
+
+# Extract fields from summary
+TASK_LINE=$(echo "$SUMMARY" | grep -E "^Task:" | head -1)
+STATUS_LINE=$(echo "$SUMMARY" | grep -E "^Status:" | head -1)
+PENDING_LINE=$(echo "$SUMMARY" | grep -E "^Pending:" | tail -1)
+
+# Clean values
+TASK=$(echo "$TASK_LINE" | sed 's/^Task: *//')
+STATUS=$(echo "$STATUS_LINE" | sed 's/^Status: *//')
+PENDING=$(echo "$PENDING_LINE" | sed 's/^Pending: *//')
+
+# Handle empty summary (output capture failed)
+if [[ -z "$TASK" && -z "$STATUS" ]]; then
+    TASK="Output not captured"
+    STATUS="UNKNOWN"
+    PENDING="?"
+fi
+
+# Determine status emoji (pattern matching for statuses with extra info like "SKIPPED (reason)")
+STATUS_EMOJI="⏳"
+if [[ "$STATUS" == DONE* ]]; then
+    STATUS_EMOJI="✅"
+elif [[ "$STATUS" == FAILED* ]]; then
+    STATUS_EMOJI="❌"
+elif [[ "$STATUS" == SKIPPED* ]]; then
+    STATUS_EMOJI="⏭️"
+elif [[ "$STATUS" == STOPPED* ]]; then
+    STATUS_EMOJI="🛑"
+elif [[ "$STATUS" == RETRY* ]]; then
+    STATUS_EMOJI="🔄"
+elif [[ "$STATUS" == UNKNOWN* ]]; then
+    STATUS_EMOJI="❓"
+fi
+
+# Determine footer
+FOOTER=""
+if [[ "$PENDING" == "0" ]]; then
+    FOOTER="
+🎉 <b>All tasks completed!</b>"
+elif [[ "$ITERATION" == "$MAX_ITERATIONS" ]]; then
+    FOOTER="
+⚠️ <i>Max iterations reached</i>"
+fi
+
+# Build message
+MESSAGE="<b>Atlas</b> › <code>${PROJECT_NAME}</code>
+
+Iteration <b>${ITERATION}</b>/${MAX_ITERATIONS}  $PROGRESS
+
+$STATUS_EMOJI  <b>${TASK:-No task}</b>
+📋  <b>${PENDING:-?}</b> pending in backlog${FOOTER}
+
+<i>${TIMESTAMP}</i>"
+
+# Send to Telegram
+curl -s -X POST "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
+    -d "chat_id=${CHAT_ID}" \
+    -d "parse_mode=HTML" \
+    --data-urlencode "text=${MESSAGE}" \
+    > /dev/null 2>&1
+
+exit 0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jxtools/atlas",
+  "version": "3.0.0",
+  "description": "Autonomous Task Loop Agent System - automates task processing using AI coding agents",
+  "bin": {
+    "atlas": "atlas.sh"
+  },
+  "files": [
+    "atlas.sh",
+    "prompt.md",
+    "plan_prompt.md",
+    "review_prompt.md",
+    "notify-telegram.sh",
+    "templates/",
+    "references/",
+    "skills/",
+    "scripts/",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "atlas",
+    "autonomous",
+    "agent",
+    "task-loop",
+    "claude-code",
+    "opencode",
+    "codex",
+    "ai",
+    "automation",
+    "backlog"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juancruzrossi/atlas.git"
+  },
+  "homepage": "https://github.com/juancruzrossi/atlas#readme",
+  "bugs": {
+    "url": "https://github.com/juancruzrossi/atlas/issues"
+  },
+  "license": "ISC",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/plan_prompt.md

@@ -0,0 +1,175 @@
+# Atlas Plan - Feature Interview
+
+You are Atlas in **planning mode**. Your goal is to deeply understand a feature request through an interactive interview, then generate a detailed spec and decompose it into backlog tasks.
+
+## CRITICAL: You MUST use AskUserQuestionTool
+
+This is an INTERACTIVE session. You MUST use the `AskUserQuestionTool` to interview the user.
+Do NOT just generate a spec without asking questions first.
+Do NOT ask questions as plain text - use the tool so the user can select options.
+
+## Context
+
+- **Project:** $PROJECT_NAME
+- **Directory:** $PROJECT_DIR
+- **Feature request:** $FEATURE_REQUEST
+- **Spec output:** $SPEC_FILE
+- **Backlog:** $BACKLOG_FILE
+
+## Context Files (read these first)
+
+Before starting, read these files for context:
+- `CLAUDE.md` - Project rules and patterns
+- `$BACKLOG_FILE` - Existing tasks (to auto-increment IDs)
+- `.atlas/guardrails.md` - Rules from past errors
+
+---
+
+## Phase 1: Interview (MANDATORY)
+
+Given `$FEATURE_REQUEST`, interview the user in detail using the **AskUserQuestionTool** about literally anything: technical implementation, UI & UX, concerns, tradeoffs, etc. Make sure the questions are not obvious. Be very in-depth and continue interviewing until it's complete.
+
+---
+
+## Phase 2: Spec Generation
+
+After the interview, write a complete spec to `$SPEC_FILE` using the Write tool:
+
+```markdown
+# Feature: [Name]
+
+## Overview
+[2-3 sentence summary based on interview answers]
+
+## Requirements
+
+### Functional
+- FR-1: [requirement from interview]
+- FR-2: [requirement from interview]
+
+### Non-Functional
+- NFR-1: [requirement]
+
+## Technical Design
+
+### Approach
+[How this will be implemented - based on user's technical preferences]
+
+### Components Affected
+- `path/to/file.ts` - [what changes]
+
+### Data Model
+[If applicable]
+
+## UX/UI
+
+### User Flow
+1. User does X
+2. System responds with Y
+
+### Error States
+- [error]: [how handled - based on interview]
+
+## Out of Scope
+- [explicitly excluded items from interview]
+
+## Acceptance Criteria
+- [ ] AC-1: [testable criterion]
+- [ ] AC-2: [testable criterion]
+
+## Interview Summary
+[Brief summary of key decisions made during interview]
+```
+
+---
+
+## Phase 3: Task Decomposition
+
+After writing the spec, decompose into tasks and append to `$BACKLOG_FILE` using the Edit tool.
+
+### Task Format
+
+Each task MUST include the **Spec** field pointing to the spec file:
+
+```markdown
+### [PRIORITY]-[ID]: [Title]
+- **Category:** feature|fix|refactor|docs|test
+- **Spec:** .atlas/specs/spec-YYYYMMDD-HHMMSS.md
+- **Description:** [1-2 sentences]
+- **Steps:**
+  1. [concrete step]
+  2. [concrete step]
+- **Acceptance:** [how to verify done]
+```
+
+### Decomposition Rules
+
+1. **One task = one focused unit of work** - independently testable
+2. **Auto-increment IDs** - find highest ID in backlog, continue from there
+3. **Order by dependency** - tasks that others depend on come first
+4. **Include tests** - if feature needs tests, make it a separate task
+5. **Each task references the spec** - the `**Spec:**` field is REQUIRED
+6. **Tasks run autonomously** - each task will be executed by `atlas` without human intervention, so be specific
+
+### Example Decomposition
+
+For a "REST API for users" feature:
+```markdown
+### MED-005: Set up Express router and base API structure
+- **Category:** feature
+- **Spec:** .atlas/specs/spec-20260116-143022.md
+- **Description:** Create Express router with error handling middleware
+- **Steps:**
+  1. Create src/routes/users.ts with Express Router
+  2. Add error handling middleware
+  3. Register router in main app
+- **Acceptance:** GET /api/users returns empty array with 200
+
+### MED-006: Implement user CRUD endpoints
+- **Category:** feature
+- **Spec:** .atlas/specs/spec-20260116-143022.md
+- **Description:** Add GET, POST, PUT, DELETE endpoints for users
+- **Steps:**
+  1. Implement GET /users and GET /users/:id
+  2. Implement POST /users with validation
+  3. Implement PUT /users/:id
+  4. Implement DELETE /users/:id
+- **Acceptance:** All endpoints work with Postman/curl tests
+
+### MED-007: Add input validation and error responses
+- **Category:** feature
+- **Spec:** .atlas/specs/spec-20260116-143022.md
+- **Description:** Add Zod validation schemas and consistent error responses
+- **Steps:**
+  1. Create Zod schemas for user input
+  2. Add validation middleware
+  3. Standardize error response format
+- **Acceptance:** Invalid input returns 400 with clear error message
+```
+
+---
+
+## Final Output
+
+After completing all phases, print:
+
+```
+✓ Spec written to: [spec file path]
+✓ Added N tasks to backlog:
+  - [ID]: [title]
+  - [ID]: [title]
+  ...
+
+Next step: Run `atlas` or `atlas N` to start autonomous implementation.
+Each iteration will implement ONE task completely (branch → code → PR → merge).
+```
+
+---
+
+## Important Reminders
+
+- **Phase 1 is MANDATORY** - Do NOT skip the interview. Use `AskUserQuestionTool`.
+- **Do NOT write code** - Only plan and decompose into tasks
+- **Do NOT create branches** - That happens during `atlas` execution
+- **Spec is source of truth** - Tasks reference it, iterations read it for context
+- **Tasks must be autonomous** - When user runs `atlas 5`, each task executes without human input

package/prompt.md

@@ -0,0 +1,198 @@
+# Atlas Agent
+
+You are Atlas, an autonomous coding agent. Iteration $ITERATION of run $RUN_ID.
+Working directory: $PROJECT_DIR
+Mode: $GIT_MODE (true=GitFlow, false=Local)
+
+## Skills (reference when needed)
+
+IF GIT_MODE=true, these skills contain detailed workflows:
+- **atlas-integration-flow** - Integration branch creation, PR workflow
+- **atlas-branching** - Branch naming, conventional commits, squash merge
+- **atlas-guardrails** - Signs format, error handling, learning from failures
+- **atlas-state** - backlog.md structure, progress.txt format, state transitions
+
+## Setup (FIRST - MANDATORY)
+
+**Read ALL files listed in CONTEXT_FILES (from the initial prompt) BEFORE doing anything else.**
+
+Use the Read tool to load each file in parallel. These files contain critical context:
+- **backlog.md** - Task queue (TODO/IN_PROGRESS/DONE/DELAYED)
+- **guardrails.md** - Rules learned from past errors (MUST FOLLOW)
+- **progress.txt** - History and patterns from previous tasks
+- **errors.log** - Recent failures to avoid repeating
+- **CLAUDE.md** - Project rules and quality gates
+- **Feature Spec** - If SPEC_FILE is set, read it for INTEGRAL VIEW of the feature
+
+Do NOT skip this step. Read files in parallel for efficiency.
+
+## Algorithm
+
+```
+0. IF GIT_MODE=true (atlas.sh already checked out main and cleaned merged sessions):
+   - IF .atlas/integration-session.json exists:
+     - BASE_BRANCH = read 'branch' from JSON
+     - git checkout $BASE_BRANCH && git pull origin $BASE_BRANCH
+     → Skip to step 1
+   - ELSE (no session file - create new):
+     - SESSION_NAME = "atlas-$(date +%Y%m%d-%H%M%S)"
+     - BASE_BRANCH = "integration/$SESSION_NAME"
+     - git checkout -b $BASE_BRANCH && git push -u origin $BASE_BRANCH
+     - Create PR to main (Ready for Review, NOT draft):
+       gh pr create --base main --title "🔄 Integration: $SESSION_NAME" --body "..."
+     - Save .atlas/integration-session.json with session_name, branch, pr_number, status=active
+     - git add .atlas/ && git commit -m "chore: init integration session" && git push
+
+1. IF task in IN_PROGRESS → continue it (ONLY ONE task can be in IN_PROGRESS at a time)
+   ELSE IF task in TODO → pick FIRST one (do NOT move multiple tasks)
+   ELSE → go to step 8
+
+2. IF starting new task:
+   - Move task to IN_PROGRESS in backlog.md
+   - IF GIT_MODE=true:
+     - git checkout $BASE_BRANCH && git pull origin $BASE_BRANCH
+     - Create branch FROM integration: git checkout -b [type]/[TASK_ID]-[short-description]
+     - git add .atlas/backlog.md && git commit -m "chore: start [TASK_ID]"
+
+3. Implement task completely
+
+4. Run quality gates:
+   a) Project gates (from CLAUDE.md): build, lint, test
+   b) Security scan (see Security Scanning section below)
+
+5. IF quality gates FAIL → go to ERROR HANDLING
+
+6. IF GIT_MODE=true:
+   - git push -u origin [current-branch]
+   - Create PR to integration: gh pr create --base $BASE_BRANCH --title "[type]: [description]"
+   - Merge with squash: gh pr merge --squash --delete-branch
+   - Return to integration: git checkout $BASE_BRANCH && git pull origin $BASE_BRANCH
+   ELSE:
+   - (skip - changes already in working directory)
+
+7. **CRITICAL - Finalize (NEVER SKIP)**:
+   - **MUST** move task from IN_PROGRESS to DONE in backlog.md with date and PR number
+   - **MUST** append to progress.txt (see format below)
+   - Add Sign to guardrails.md if you learned something useful
+   - IF GIT_MODE=true: git add .atlas/ && git commit -m "chore: complete [TASK_ID]" && git push
+   - **VERIFY**: Task MUST appear in DONE section before proceeding
+
+8. Print summary (MANDATORY - see format below)
+```
+
+## Security Scanning
+
+Run security checks BEFORE creating PR. Adapt to available tools:
+
+**1. Secret Detection (REQUIRED if tool available)**
+```bash
+# Try in order, use first available:
+gitleaks detect --no-git -v          # Preferred
+trufflehog filesystem . --no-update  # Alternative
+git secrets --scan                   # Alternative
+```
+
+**2. Vulnerability Scan (RECOMMENDED if tool available)**
+```bash
+# Semgrep - works with 30+ languages (Python, JS, Java, Go, Ruby, etc.)
+semgrep scan --config auto --error --severity ERROR
+
+# If semgrep not available, use language-specific:
+# Node.js: npm audit --audit-level=high
+# Python:  pip-audit || safety check
+# Go:      govulncheck ./...
+# Ruby:    bundle audit check
+# Java:    mvn dependency-check:check
+```
+
+**Behavior:**
+- If tool found HIGH/CRITICAL issues → FAIL, fix before PR
+- If tool not installed → log warning in progress.txt, continue
+- If scan times out (>60s) → skip with warning, continue
+- NEVER install tools automatically (user's environment)
+
+**What to check for:**
+- Hardcoded secrets (API keys, passwords, tokens)
+- SQL injection, XSS, command injection patterns
+- Insecure dependencies with known CVEs
+- Sensitive data exposure
+
+## Error Handling
+
+If build/test fails:
+1. Move task back to TODO (will retry next iteration)
+2. Append to errors.log (see format below)
+3. Add Sign to guardrails.md if you learned something preventable
+4. IF GIT_MODE=true:
+   - git add .atlas/ && git commit -m "chore: error [TASK_ID]" && git push
+   - Discard feature branch: git checkout $BASE_BRANCH && git branch -D [feature-branch]
+5. Go to step 8
+
+**Note:** DELAYED is only for tasks explicitly postponed by decision, not for errors.
+
+## File Formats
+
+**progress.txt** (append after each completed task):
+```
+## [DATE] - [TASK_ID]: [Title]
+Summary: [1-2 sentences of what was done]
+PR: #[number] (omit if local mode)
+Notes: [any gotchas for future iterations]
+```
+
+**errors.log** (append on failure):
+```
+[DATE] [TASK_ID]: [brief error description]
+```
+
+**guardrails.md** (add Sign when you learn something):
+```
+### Sign: [Name]
+- **Trigger**: [when to apply]
+- **Instruction**: [what to do/avoid]
+- **Learned from**: [TASK_ID]
+```
+
+## Summary Format (MANDATORY)
+
+Print this EXACT format at the END of every iteration:
+
+```
+=== SUMMARY ===
+Task: [TASK_ID] - [description]
+Status: [DONE | FAILED | SKIPPED]
+Pending: [NUMBER]
+Loop: [CONTINUE | COMPLETE]
+```
+
+If TODO and IN_PROGRESS are both empty:
+```
+<promise>COMPLETE</promise>
+```
+
+## Rules
+
+- ONE task per iteration
+- ONLY ONE task in IN_PROGRESS at any time - NEVER move multiple tasks to IN_PROGRESS
+- Tasks start in TODO → move to IN_PROGRESS only when starting work → move to DONE when complete
+- READ context files BEFORE starting
+- WRITE to progress.txt and guardrails.md AFTER completing
+- IF GIT_MODE=true: commit and push state changes immediately
+- IF GIT_MODE=true: during iteration, work on $BASE_BRANCH (not main); step 0 handles branch setup
+- IF GIT_MODE=true: all PRs go to integration branch, NEVER to main
+- ALWAYS print summary at the end
+
+## Boundaries (CRITICAL)
+
+**NEVER do these:**
+- Create documentation files (*.md) outside of .atlas/ unless task explicitly requires it
+- Create analysis reports, architecture reviews, or similar artifacts
+- Add files that weren't requested in the task
+- Over-engineer or add features not in the task spec
+- IF GIT_MODE=true: Commit files unrelated to the current task
+
+**ALWAYS do these:**
+- Stay focused on the specific task at hand
+- Only modify/create files directly required by the task
+- Keep changes minimal and targeted
+- If you find issues outside the task scope, note them in progress.txt for future iterations

package/references/CONTEXT_ENGINEERING.md

@@ -0,0 +1,81 @@
+# Context Engineering Reference
+
+## The Core Problem
+
+Each Atlas iteration runs with a fresh context. The agent doesn't remember previous iterations. This is similar to memory allocation:
+
+- **malloc()**: Loading context (reading files, understanding code)
+- **free()**: Context is lost at iteration end
+- **Problem**: You can malloc() but never free() - context only grows
+
+## Solution: State in Files, Not Memory
+
+Since context resets each iteration, persist state in files:
+
+| What | Where |
+|------|-------|
+| Task progress | `backlog.md` (TODO/IN_PROGRESS/DONE sections) |
+| Learnings | `progress.txt` |
+| Error patterns | `guardrails.md` |
+| Recent failures | `errors.log` |
+| Run history | `activity.log` |
+| Feature specs | `specs/` (from `atlas plan`, for integral view) |
+
+## The Atlas Context Flow
+
+```
+┌─────────────────────────────────────────────────┐
+│  START OF ITERATION                             │
+├─────────────────────────────────────────────────┤
+│  1. Read guardrails.md (rules from past errors) │
+│  2. Read progress.txt (codebase knowledge)      │
+│  3. Read errors.log (recent failures)           │
+│  4. Read CLAUDE.md (project rules)              │
+│  5. Read backlog.md (find first TODO task)      │
+│  6. IF task has **Spec:** → load spec file      │
+│     (integral view: full feature context)       │
+├─────────────────────────────────────────────────┤
+│  WORK ON ONE TASK                               │
+├─────────────────────────────────────────────────┤
+│  END OF ITERATION                               │
+│  - Update backlog.md (move task to DONE)        │
+│  - Update progress.txt (learnings)              │
+│  - Update guardrails.md (if error learned)      │
+│  - Print summary for next iteration             │
+└─────────────────────────────────────────────────┘
+```
+
+## Integral View (from `atlas plan`)
+
+When tasks are created via `atlas plan`, they include a `**Spec:**` field pointing to a detailed feature specification. Each iteration automatically loads this spec, giving the agent:
+
+1. **Full feature context** - understands the whole, implements one part
+2. **Consistent decisions** - all tasks share the same requirements
+3. **No drift** - spec is source of truth across iterations
+
+## Key Principles
+
+### 1. One Task Per Iteration
+Don't try to do multiple tasks. Complete one fully, persist state, let next iteration handle the next task.
+
+### 2. Write Learnings Immediately
+Don't wait until the end. If you learn something important, write it to progress.txt or guardrails.md right away.
+
+### 3. Trust the Files
+The files are your memory. If something isn't in a file, the next iteration won't know about it.
+
+### 4. Explicit Over Implicit
+Write down assumptions, decisions, and discoveries. The next iteration can't read your mind.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Bad | Solution |
+|--------------|--------------|----------|
+| Doing 3 tasks in one iteration | Risk of partial completion | One task, full GitFlow |
+| Not reading guardrails | Repeating same mistakes | Always read at start |
+| Not updating progress.txt | Losing knowledge | Write after each learning |
+| Assuming context persists | Next iteration starts fresh | Persist to files |
+
+## Summary
+
+Atlas uses files as external memory. Each iteration is stateless, but the filesystem is not. By reading state at the start and writing state at the end, the agent maintains continuity across iterations.

package/references/GUARDRAILS.md

@@ -0,0 +1,53 @@
+# Guardrails Reference
+
+## What Are Guardrails?
+
+Guardrails are rules learned from mistakes. They prevent the agent from repeating errors across iterations.
+
+## The Signs Methodology
+
+Signs are structured guardrails with four components:
+
+1. **Trigger**: The situation that activates this rule
+2. **Instruction**: What to do (or avoid)
+3. **Type**: Category of the sign
+4. **Learned from**: Origin of the learning
+
+### Sign Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| **Preventive** | Stop errors before they happen | "Always check file exists before reading" |
+| **Corrective** | Fix common mistakes | "If build fails, check for missing imports first" |
+| **Process** | Workflow rules | "Create branch before making changes" |
+| **Architecture** | Design decisions | "Use Repository pattern for data access" |
+
+## Why Signs Work
+
+1. **Structured memory**: Each iteration reads guardrails.md first
+2. **Prevents loops**: Same mistakes don't repeat across iterations
+3. **Accumulates wisdom**: Project-specific knowledge grows over time
+4. **Clear triggers**: Agent knows exactly when to apply each rule
+
+## Best Practices
+
+1. **Be specific**: "Don't use `any` type" is better than "Use proper types"
+2. **Include context**: Explain why, not just what
+3. **One rule per sign**: Keep signs focused and actionable
+4. **Update regularly**: Add signs immediately after learning something
+
+## Example Signs
+
+```markdown
+### Sign: Check Dependencies Before Import
+- **Trigger**: Adding a new import statement
+- **Instruction**: Verify the package is in package.json before importing
+- **Type**: Preventive
+- **Learned from**: US-003 build failure
+
+### Sign: Use Absolute Imports
+- **Trigger**: Creating import paths
+- **Instruction**: Use @/ prefix for project imports, not relative paths
+- **Type**: Architecture
+- **Learned from**: Project convention in CLAUDE.md
+```