@jxtools/atlas 3.0.0

package/skills/atlas-integration-flow/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: atlas-integration-flow
+description: |
+  Integration branch workflow for Atlas autonomous sessions. ONLY use when
+  running as Atlas agent (detected by GIT_MODE=true in prompt context).
+  Handles: creating integration branch, PR workflow to integration,
+  PR to main (Ready for Review). Use when: (1) starting Atlas session with git,
+  (2) creating PRs during Atlas run, (3) completing Atlas session.
+
+  IMPORTANT: When using Atlas specialized agents, invoke this skill for git operations.
+author: Atlas
+version: 1.1.0
+date: 2026-01-23
+---
+
+# Atlas Integration Branch Flow
+
+**CRITICAL**: Only apply this workflow when running as Atlas agent with GIT_MODE=true.
+
+## Overview
+
+All Atlas work goes to an integration branch, NOT directly to main. This allows human review of all changes before merging to main.
+
+```
+main (protected)
+  │
+  └── integration/atlas-YYYYMMDD-HHMMSS  ← PR to main (Ready for Review, NO merge until review)
+        │
+        ├── feature/TASK-001  → PR to integration ✓ merged
+        ├── feature/TASK-002  → PR to integration ✓ merged
+        └── fix/TASK-003      → PR to integration ✓ merged
+```
+
+## Step 0: Start Every Iteration
+
+**CRITICAL**: ALWAYS start from main, then check for existing session.
+
+```bash
+# 1. ALWAYS start from main
+git checkout main && git pull origin main
+
+# 2. Check for existing session
+if [[ -f .atlas/integration-session.json ]]; then
+  PR_NUMBER=$(grep '"pr_number"' .atlas/integration-session.json | sed 's/[^0-9]//g')
+  PR_STATE=$(gh pr view "$PR_NUMBER" --json state -q '.state')
+
+  if [[ "$PR_STATE" == "MERGED" ]]; then
+    # Session was merged - cleanup locally and create new
+    BRANCH=$(grep '"branch"' .atlas/integration-session.json | sed 's/.*"branch"[[:space:]]*:[[:space:]]*"//;s/".*//')
+    git branch -D "$BRANCH" 2>/dev/null || true  # Delete local branch
+    rm .atlas/integration-session.json  # Delete locally (no commit to main - it's protected)
+    # Continue to create new session below
+  else
+    # Session still active - use it
+    BASE_BRANCH=$(grep '"branch"' .atlas/integration-session.json | sed 's/.*"branch"[[:space:]]*:[[:space:]]*"//;s/".*//')
+    git checkout "$BASE_BRANCH" && git pull origin "$BASE_BRANCH"
+    # Skip to step 1
+  fi
+fi
+```
+
+## Creating New Integration Session
+
+**When no session exists** (first iteration or after cleanup):
+
+```bash
+# 1. Generate session name
+SESSION_NAME="atlas-$(date +%Y%m%d-%H%M%S)"
+BASE_BRANCH="integration/$SESSION_NAME"
+
+# 2. Create integration branch (already on main from step 0)
+git checkout -b "$BASE_BRANCH"
+git push -u origin "$BASE_BRANCH"
+
+# 3. Create PR to main - Ready for Review, NOT draft (REQUIRED)
+PR_URL=$(gh pr create --base main \
+  --title "🔄 Integration: $SESSION_NAME" \
+  --body "## Integration Branch
+
+⚠️ **NO MERGEAR** hasta revisión completa.
+
+### PRs incluidos
+_Se actualizará con cada feature mergeada_
+
+### Checklist
+- [ ] Code review completo
+- [ ] Tests passing
+- [ ] Sin conflictos con main
+")
+PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$')
+
+# 4. Create session file (.atlas/ already exists from atlas init)
+cat > .atlas/integration-session.json << EOF
+{
+  "session_name": "$SESSION_NAME",
+  "branch": "$BASE_BRANCH",
+  "pr_number": $PR_NUMBER,
+  "status": "active",
+  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF
+
+# 5. Commit session file
+git add .atlas/integration-session.json
+git commit -m "chore: init integration session $SESSION_NAME"
+git push
+```
+
+## Why Start from Main?
+
+If you start directly on an old integration branch:
+1. The user may have already merged the PR on GitHub
+2. You'd be working on a stale branch
+3. New Atlas runs would start from the wrong base
+
+By ALWAYS starting from main and checking PR state, we ensure:
+- Fresh state on every iteration start
+- Automatic cleanup of merged sessions
+- New sessions created from latest main
+
+## Creating Feature Branches
+
+Always create from integration branch:
+
+```bash
+# CORRECT
+git checkout "$BASE_BRANCH"
+git pull origin "$BASE_BRANCH"
+git checkout -b feature/TASK-001-description
+
+# WRONG - never branch from main during Atlas session
+git checkout main  # NO!
+```
+
+## Creating PRs
+
+**Target integration branch, NOT main**:
+
+```bash
+# CORRECT
+gh pr create --base "$BASE_BRANCH" --title "feat: description"
+
+# WRONG
+gh pr create --base main  # NO! Never during Atlas session
+```
+
+## Merging PRs
+
+```bash
+# Squash merge to integration
+gh pr merge --squash --delete-branch
+
+# Return to integration branch
+git checkout "$BASE_BRANCH"
+git pull origin "$BASE_BRANCH"
+```
+
+## CRITICAL: Update Backlog After Merge
+
+**IMMEDIATELY after merging a PR, you MUST update the backlog:**
+
+```bash
+# 1. Move task from IN_PROGRESS to DONE in backlog.md
+#    Add completion date and PR number
+
+# 2. Append to progress.txt with summary
+
+# 3. Commit and push state changes
+git add .atlas/
+git commit -m "chore: complete [TASK_ID]"
+git push
+```
+
+**NEVER proceed to the next task without updating the backlog.**
+This is the most common source of state drift - tasks get completed but backlog shows them as pending.
+
+**Verification**: Before starting a new task, confirm the previous task appears in the DONE section of backlog.md.
+
+## End of Session
+
+The integration branch stays with PR open to main (Ready for Review). Human reviews and merges when ready.
+
+**DO NOT**:
+- Merge integration PR to main automatically
+- Delete integration branch before human review
+
+## Session File Format
+
+```json
+{
+  "session_name": "atlas-20260119-155537",
+  "branch": "integration/atlas-20260119-155537",
+  "pr_number": 28,
+  "status": "active",
+  "created_at": "2026-01-19T15:55:37Z"
+}
+```
+
+## Error Recovery
+
+If integration branch gets out of sync:
+```bash
+git checkout "$BASE_BRANCH"
+git pull origin "$BASE_BRANCH"
+# If conflicts, resolve them on integration branch
+```
+
+If session file is corrupted, check GitHub for the integration branch and PR number, then recreate the file.

package/skills/atlas-state/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: atlas-state
+description: |
+  State file management for Atlas autonomous agent. ONLY use when running
+  as Atlas agent. Covers: backlog.md structure, progress.txt format,
+  errors.log format, activity.log. Use when: (1) moving tasks between states,
+  (2) logging progress, (3) recording errors.
+
+  CRITICAL: Only ONE task can be in IN_PROGRESS at a time. Tasks start in TODO,
+  move to IN_PROGRESS when work begins, then to DONE when complete.
+
+  IMPORTANT: When using Atlas specialized agents, invoke this skill for state management.
+author: Atlas
+version: 1.1.0
+date: 2026-01-23
+---
+
+# Atlas State Management
+
+**CRITICAL**: Only apply when running as Atlas agent.
+
+## File Locations
+
+All state files live in `.atlas/` directory:
+
+```
+.atlas/
+├── backlog.md      # Task queue
+├── progress.txt    # Completed task history
+├── guardrails.md   # Learned rules
+├── errors.log      # Error history
+├── activity.log    # Run history (managed by atlas.sh)
+├── runs/           # Per-iteration logs
+└── specs/          # Feature specifications
+```
+
+## backlog.md Structure
+
+```markdown
+# [Project] Backlog
+
+## TODO
+
+### TASK-001: Task title
+- **Category:** feature|fix|refactor|test|docs|chore
+- **Spec:** .atlas/specs/spec-YYYYMMDD-HHMMSS.md (optional)
+- **Description:** Brief description (optional)
+
+### TASK-002: Another task
+- **Category:** fix
+
+## IN_PROGRESS
+
+### TASK-003: Current task (STARTED: 2026-01-19)
+- **Category:** feature
+
+## DONE
+
+### TASK-004: Completed task (2026-01-19) - PR #123
+- **Category:** feature
+
+## DELAYED
+
+### TASK-005: Blocked task (DELAYED: 2026-01-19)
+- **Category:** feature
+- **Delay reason:** Missing API credentials
+```
+
+### Moving Tasks
+
+**TODO → IN_PROGRESS**:
+```markdown
+# Before (in TODO)
+### TASK-001: Add feature
+
+# After (in IN_PROGRESS)
+### TASK-001: Add feature (STARTED: 2026-01-19)
+```
+
+**IN_PROGRESS → DONE**:
+```markdown
+# Before (in IN_PROGRESS)
+### TASK-001: Add feature (STARTED: 2026-01-19)
+
+# After (in DONE)
+### TASK-001: Add feature (2026-01-19) - PR #45
+```
+
+**IN_PROGRESS → DELAYED**:
+```markdown
+# Before (in IN_PROGRESS)
+### TASK-001: Add feature (STARTED: 2026-01-19)
+
+# After (in DELAYED)
+### TASK-001: Add feature (DELAYED: 2026-01-19)
+- **Delay reason:** Build fails due to missing dependency
+```
+
+### Task Selection
+
+1. If task in IN_PROGRESS → continue that task
+2. If no task in IN_PROGRESS → pick FIRST task from TODO
+3. If TODO and IN_PROGRESS empty → session complete
+
+**CRITICAL RULES:**
+- **ONLY ONE** task can be in IN_PROGRESS at any time
+- **NEVER** move multiple tasks to IN_PROGRESS
+- **NEVER** skip tasks - ALWAYS pick the first one from TODO
+- Tasks flow: TODO → IN_PROGRESS → DONE (one at a time)
+- **NEVER** proceed to next task without moving current task to DONE
+- **ALWAYS** update backlog.md IMMEDIATELY after merging PR
+- **VERIFY** task is in DONE section before starting new task
+
+## progress.txt Format
+
+Append after each completed task:
+
+```markdown
+## [DATE] - [TASK_ID]: [Title]
+Summary: [1-2 sentences of what was done]
+PR: #[number]
+Notes: [any gotchas for future iterations]
+```
+
+**Example**:
+```markdown
+## 2026-01-19 - HIGH-001: Create user authentication
+Summary: Implemented JWT auth with refresh tokens. Added login/logout endpoints.
+PR: #45
+Notes: Refresh token rotation requires Redis, see .env.example for config.
+
+## 2026-01-19 - HIGH-002: Add password reset
+Summary: Added forgot password flow with email verification.
+PR: #46
+Notes: Email templates in templates/email/. Requires SMTP config.
+```
+
+### What to Include
+
+- **Summary**: What was implemented, high-level
+- **PR**: The PR number for reference
+- **Notes**: Things future iterations should know
+
+### What NOT to Include
+
+- Code snippets (too verbose)
+- Full file paths (summarize instead)
+- Debug information
+- Time spent
+
+## errors.log Format
+
+One line per error:
+
+```
+[DATE] TASK_ID: Brief error description
+```
+
+**Examples**:
+```
+[2026-01-19] HIGH-003: Build failed - TypeScript error in UserService
+[2026-01-19] MED-007: Tests failed - Mock not configured for external API
+[2026-01-19] LOW-012: Blocked - Missing API credentials in .env
+```
+
+Keep it brief. Details go in progress.txt or guardrails.md.
+
+## State Commits
+
+After modifying state files, commit immediately:
+
+```bash
+# Starting task
+git add .atlas/backlog.md
+git commit -m "chore: start TASK-001"
+
+# Completing task
+git add .atlas/
+git commit -m "chore: complete TASK-001"
+
+# Delaying task
+git add .atlas/
+git commit -m "chore: delay TASK-001"
+```
+
+**IMPORTANT**: Push after commit when GIT_MODE=true:
+```bash
+git push
+```
+
+## Integration with Specs
+
+If task has a `**Spec:**` field, read that spec for full context:
+
+```markdown
+### HIGH-005: Implement payment flow
+- **Category:** feature
+- **Spec:** .atlas/specs/spec-20260119-143022.md
+```
+
+The spec contains:
+- Full requirements
+- Acceptance criteria
+- Technical decisions
+- Edge cases
+
+**ALWAYS read the spec before starting a task that has one.**
+
+## Session Complete
+
+When TODO and IN_PROGRESS are both empty:
+
+1. Print summary
+2. Output `<promise>COMPLETE</promise>`
+3. Atlas loop will exit
+
+```markdown
+=== SUMMARY ===
+Task: [last task completed]
+Status: DONE
+Pending: 0
+Loop: COMPLETE
+
+<promise>COMPLETE</promise>
+```

package/templates/backlog.md

@@ -0,0 +1,27 @@
+# [PROJECT_NAME] Backlog
+
+## TODO
+
+### HIGH-001: Example task - DELETE THIS
+- **Category:** feature
+- **Description:** Replace this with your first real task
+- **Steps:**
+  1. Step 1
+  2. Step 2
+
+<!-- Tasks from `atlas plan` include **Spec:** field for integral view:
+### MED-002: Example planned task
+- **Category:** feature
+- **Spec:** .atlas/specs/spec-20260116-120000.md
+- **Description:** Task generated from feature spec
+- **Steps:**
+  1. Step 1
+  2. Step 2
+- **Acceptance:** How to verify done
+-->
+
+## IN_PROGRESS
+
+## DONE
+
+## DELAYED

package/templates/guardrails.md

@@ -0,0 +1,69 @@
+# Guardrails
+
+> Rules learned from errors and gotchas. Atlas reads this at the start of every iteration.
+
+## How to Add Signs
+
+When you encounter an error or learn something the hard way, add a Sign:
+
+```markdown
+### Sign: [Descriptive Name]
+- **Trigger**: When does this apply?
+- **Instruction**: What to do (or NOT do)
+- **Type**: Preventive | Corrective | Process | Architecture
+- **Learned from**: Task ID or iteration
+```
+
+## Core Signs
+
+### Sign: Always Read Before Edit
+- **Trigger**: Before modifying any file
+- **Instruction**: Always read the current file content before making changes
+- **Type**: Preventive
+- **Learned from**: Best practice
+
+### Sign: One Task Per Iteration
+- **Trigger**: When tempted to do multiple tasks
+- **Instruction**: Complete ONE task fully before moving to the next
+- **Type**: Process
+- **Learned from**: Atlas design principle
+
+### Sign: Verify Build After Changes
+- **Trigger**: After any code modification
+- **Instruction**: Run build/lint/test commands before marking task complete
+- **Type**: Corrective
+- **Learned from**: Best practice
+
+### Sign: Security Scan Before PR
+- **Trigger**: Before creating a pull request
+- **Instruction**: Run available security tools (gitleaks, semgrep, npm audit, etc.) and fix HIGH/CRITICAL issues. Skip with warning if tools not installed.
+- **Type**: Preventive
+- **Learned from**: Best practice
+
+---
+
+## Boundaries
+
+### ✅ Always
+- Run existing tests before committing changes
+- Read file contents before making edits
+- Use available agents and skills when they fit the task
+- Follow project naming conventions and code style
+- Verify CI/PR checks pass before requesting merge
+- Write clear, conventional commit messages
+- Validate changes work before marking task complete
+
+### 🚫 Never
+- Commit secrets, credentials, or API keys
+- Force push to protected branches without explicit approval
+- Delete or skip failing tests without explicit approval
+- Bypass quality gates (linter, formatter, type checker, tests)
+- Leave temporary debug code in production
+- Edit auto-generated files directly (modify the source instead)
+- Ignore compiler/linter warnings without justification
+
+---
+
+## Project-Specific Signs
+
+<!-- Add signs learned during this project below -->

package/templates/progress.txt

@@ -0,0 +1,14 @@
+# Progress Log
+
+Atlas automatically appends entries here after completing each task.
+
+Format:
+```
+## [DATE] - [TASK_ID]: [Title]
+Summary: [1-2 sentences of what was done]
+PR: #[number] (omit if local mode)
+Notes: [any gotchas for future iterations]
+```
+
+================================================================================
+