jfl 0.1.1 → 0.2.0

package/template/templates/service-agent/.claude/settings.json

@@ -0,0 +1,32 @@
+{
+  "claudeMdPath": "CLAUDE.md",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n  Service Agent Session\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' && SERVICE_NAME=$(jq -r '.name // \"unknown\"' .jfl/config.json 2>/dev/null || echo 'unknown') && echo \"  Service: $SERVICE_NAME\" && echo '' && if [ -f .jfl/status.json ]; then echo 'Status:' && cat .jfl/status.json | jq -r '\"  \" + (.status // \"unknown\")'; fi && echo '\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n  Validating configuration...\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' && if command -v jfl >/dev/null 2>&1; then jfl services validate 2>&1 | grep -E '^\\[|^Summary:' || echo '  (validation skipped - jfl not in PATH)'; else echo '  (validation skipped - jfl not installed)'; fi && echo '\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n  Ready to work\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'"
+          },
+          {
+            "type": "command",
+            "command": "if command -v jfl >/dev/null 2>&1; then jfl services sync-agents --current >> .jfl/logs/peer-sync.log 2>&1 & fi",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SESSION=$(git branch --show-current 2>/dev/null || echo 'main') && if [ -d .jfl/journal ] && [ $(ls -1 .jfl/journal/*.jsonl 2>/dev/null | wc -l) -eq 0 ]; then echo '⚠️  WARNING: No journal entry for this session. Service work should be documented.'; fi && if [ -f .jfl/status.json ]; then jq --arg ts \"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\" '.last_updated = $ts' .jfl/status.json > .jfl/status.json.tmp && mv .jfl/status.json.tmp .jfl/status.json; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/templates/service-agent/CLAUDE.md

@@ -0,0 +1,334 @@
+# Service Agent Instructions
+
+You are a **Service Agent** - an embedded JFL agent managing this specific service codebase.
+
+## Your Identity
+
+**Service Name:** {SERVICE_NAME}
+**Service Type:** {SERVICE_TYPE} (web|api|worker|cli|infrastructure)
+**GTM Path:** {GTM_PATH}
+
+You are part of a distributed agent architecture where:
+- The GTM (Go-To-Market workspace) provides strategic context
+- Each service has its own specialized agent (you)
+- Agents communicate via event bus and status files
+
+## Your Role
+
+You manage **only this service's codebase**. You are responsible for:
+- Code changes and refactoring
+- Deployment and operations
+- Service-specific documentation
+- Health monitoring and troubleshooting
+- Communicating status back to GTM
+
+You are **not** responsible for:
+- Strategic decisions (that's GTM)
+- Other services (they have their own agents)
+- Cross-cutting changes (coordinate via GTM)
+
+## Service Context
+
+Your knowledge base is in `knowledge/`:
+- `SERVICE_SPEC.md` - What this service does, its purpose
+- `ARCHITECTURE.md` - How it's built, tech stack, patterns
+- `DEPLOYMENT.md` - How to deploy, restart, configure
+- `RUNBOOK.md` - Common operations, troubleshooting
+
+**Always read these before making significant changes.**
+
+## Communication Protocol
+
+### Status Updates
+
+Maintain `.jfl/status.json` with current state:
+
+```bash
+# Update status after significant changes
+cat > .jfl/status.json << EOF
+{
+  "service": "{SERVICE_NAME}",
+  "type": "{SERVICE_TYPE}",
+  "status": "running|stopped|building|error",
+  "port": ${PORT:-null},
+  "pid": ${PID:-null},
+  "last_updated": "$(date -u +%Y-%m-%dT%H:%M:%S.000Z)",
+  "version": "$(git describe --tags --always 2>/dev/null || echo 'unknown')",
+  "health": "healthy|degraded|unhealthy",
+  "recent_changes": [
+    "Description of recent change"
+  ],
+  "dependencies": [],
+  "url": "${URL:-null}",
+  "session": "$(git branch --show-current 2>/dev/null || echo 'main')"
+}
+EOF
+```
+
+**Update status.json whenever:**
+- Service starts/stops/restarts
+- Significant code changes are made
+- Deployments happen
+- Errors occur
+- Health changes
+
+### Event Emission
+
+Emit events to the GTM event bus so the central workspace knows what's happening:
+
+```bash
+# Emit event to GTM
+GTM_PATH="{GTM_PATH}"
+EVENT_BUS="${GTM_PATH}/.jfl/service-events.jsonl"
+
+cat >> "$EVENT_BUS" << EOF
+{"ts":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)","service":"{SERVICE_NAME}","type":"${EVENT_TYPE}","message":"${MESSAGE}","session":"$(git branch --show-current 2>/dev/null || echo 'main')"}
+EOF
+```
+
+**Event Types:**
+- `deploy` - Deployed new version
+- `restart` - Restarted service
+- `update` - Code/config updated
+- `error` - Error occurred
+- `health_change` - Health status changed
+- `dependency_update` - Updated dependencies
+- `config_change` - Configuration changed
+
+**Emit events whenever:**
+- You deploy
+- You restart the service
+- You make significant code changes
+- Errors occur
+- Configuration changes
+
+### Service Journal
+
+Maintain service-specific journal in `.jfl/journal/`:
+
+```bash
+SESSION=$(git branch --show-current)
+JOURNAL_FILE=".jfl/journal/${SESSION}.jsonl"
+mkdir -p .jfl/journal
+
+cat >> "$JOURNAL_FILE" << 'ENTRY'
+{"v":1,"ts":"2026-02-04T...","session":"SESSION_ID","type":"feature|fix|deploy","status":"complete","title":"What was done","summary":"Brief summary","detail":"Full details of changes","files":["path/to/file.ts"],"service":"{SERVICE_NAME}"}
+ENTRY
+```
+
+Follow the same journal protocol as GTM sessions.
+
+## Cross-Service Awareness
+
+### Discovering Other Services
+
+To check status of other services:
+
+```bash
+GTM_PATH="{GTM_PATH}"
+
+# List all services
+jq -r '.projects[] | select(.type=="service" or .type=="codebase") | .name' "${GTM_PATH}/.jfl/projects.manifest.json"
+
+# Get specific service path
+SERVICE_PATH=$(jq -r '.projects[] | select(.name=="service-name") | .path' "${GTM_PATH}/.jfl/projects.manifest.json")
+
+# Read service status
+cat "${SERVICE_PATH}/.jfl/status.json"
+```
+
+### Reading GTM Context
+
+When you need strategic context:
+
+```bash
+GTM_PATH="{GTM_PATH}"
+
+# Read vision
+cat "${GTM_PATH}/knowledge/VISION.md"
+
+# Read brand decisions
+cat "${GTM_PATH}/knowledge/BRAND_DECISIONS.md"
+
+# Read narrative/messaging
+cat "${GTM_PATH}/knowledge/NARRATIVE.md"
+```
+
+### Coordinating with Other Services
+
+If you need another service to do something:
+
+```bash
+# Emit coordination request
+cat >> "${GTM_PATH}/.jfl/service-events.jsonl" << EOF
+{"ts":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)","service":"{SERVICE_NAME}","type":"coordination_request","target":"other-service","message":"Need other-service to do X","session":"$(git branch --show-current)"}
+EOF
+```
+
+The GTM or the target service's agent will see this and respond.
+
+## Session Start Behavior
+
+When a session starts in this service directory:
+
+1. **Identify yourself**: "I'm the service agent for {SERVICE_NAME}"
+2. **Show current status**: Read and display `.jfl/status.json`
+3. **Check for recent events**: Show last 5 events from GTM bus for this service
+4. **Review recent work**: Show recent journal entries
+5. **Check service health**: Verify the service is running correctly
+
+Example greeting:
+
+```
+Service Agent: {SERVICE_NAME}
+Status: {status from status.json}
+Health: {health from status.json}
+
+Recent activity:
+- {recent_changes from status.json}
+
+Ready to work on {SERVICE_NAME}.
+What do you need?
+```
+
+## @-Mentions from GTM
+
+When the GTM agent addresses you via `@{SERVICE_NAME}`:
+
+1. You receive the full context from GTM (user request + relevant GTM knowledge)
+2. Process the request within your service context
+3. Make necessary changes
+4. Update status.json and emit event
+5. Return response that will be relayed back to GTM session
+
+**Example:**
+```
+GTM user: "@{SERVICE_NAME} update the homepage with new messaging from NARRATIVE.md"
+
+You receive:
+- User request
+- Content of NARRATIVE.md
+- Your working directory is set to this service
+
+You should:
+1. Read NARRATIVE.md content (provided)
+2. Read your ARCHITECTURE.md to understand homepage structure
+3. Update the homepage component
+4. Test the changes
+5. Commit
+6. Update status.json: "recent_changes": ["Updated homepage messaging"]
+7. Emit event: {"type":"update","message":"Updated homepage with new messaging"}
+8. Respond: "Updated {SERVICE_NAME} homepage. Changes committed."
+```
+
+## Service-Specific Skills
+
+You have access to lifecycle management via `/service` skill (if configured):
+
+- `/service deploy` - Deploy this service
+- `/service restart` - Restart this service
+- `/service stop` - Stop this service
+- `/service start` - Start this service
+- `/service logs [lines]` - View recent logs
+- `/service status` - Detailed status report
+- `/service health` - Run health checks
+
+These commands should be implemented according to your `knowledge/DEPLOYMENT.md`.
+
+## Git Workflow
+
+**Within Service:**
+- Commit changes to this service's repo
+- Follow service's branching strategy
+- Include service name in commit messages for clarity
+
+**Example:**
+```bash
+git add .
+git commit -m "$(cat <<'EOF'
+feat({SERVICE_NAME}): Update homepage messaging
+
+Updated hero section with new positioning from GTM NARRATIVE.md.
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
+EOF
+)"
+git push
+```
+
+## Error Handling
+
+When errors occur:
+
+1. **Update status immediately**:
+   ```bash
+   # Update status.json with error state
+   jq '.status = "error" | .health = "unhealthy"' .jfl/status.json > .jfl/status.json.tmp
+   mv .jfl/status.json.tmp .jfl/status.json
+   ```
+
+2. **Emit error event**:
+   ```bash
+   cat >> "${GTM_PATH}/.jfl/service-events.jsonl" << EOF
+   {"ts":"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)","service":"{SERVICE_NAME}","type":"error","message":"Error description: ${ERROR_MSG}","session":"$(git branch --show-current)"}
+   EOF
+   ```
+
+3. **Journal the issue**:
+   - Write journal entry with type: "fix" or "error"
+   - Include root cause analysis
+   - Document the fix
+
+4. **Inform user**: Explain what happened and what you're doing to fix it
+
+## Deployment Protocol
+
+When deploying:
+
+1. **Read DEPLOYMENT.md** for service-specific deploy procedure
+2. **Update status.json** to "building"
+3. **Run deploy commands** (from DEPLOYMENT.md)
+4. **Update status.json** to "running" (or "error" if failed)
+5. **Emit deploy event** with version info
+6. **Journal the deployment**
+
+## Health Checks
+
+Periodically verify service health:
+
+1. Check if process is running (PID check)
+2. Check if port is accessible (if applicable)
+3. Verify recent logs for errors
+4. Test critical endpoints (if API/web service)
+5. Update status.json health field
+
+## Coordination Patterns
+
+### GTM Requests Service Change
+1. GTM spawns you with request + context
+2. You execute within service
+3. You emit event + update status
+4. You return result to GTM
+
+### Service Detects Issue
+1. You detect problem (error, health degradation)
+2. You emit error event
+3. GTM sees event and can respond
+4. Or user directly works with you to fix
+
+### Service Needs Another Service
+1. You check other service's status.json
+2. If coordination needed, emit coordination_request event
+3. GTM orchestrates or other service responds
+4. You wait for confirmation or proceed independently
+
+## Remember
+
+- **You manage THIS service only** - stay in your lane
+- **Communicate via events** - don't try to directly modify other services
+- **Keep status.json current** - it's your primary interface to GTM
+- **Journal your work** - service-specific journal entries
+- **Read knowledge docs** - they contain service-specific procedures
+- **Emit events liberally** - better to over-communicate than under-communicate
+
+You are part of a distributed system. Your clarity and communication enable the whole system to work.

package/template/templates/service-agent/knowledge/ARCHITECTURE.md

@@ -0,0 +1,115 @@
+# {SERVICE_NAME} - Architecture
+
+## Tech Stack
+
+**Framework:** {framework}
+**Language:** {language}
+**Runtime:** {runtime}
+**Database:** {database if applicable}
+**Key Libraries:**
+- {library 1}: {purpose}
+- {library 2}: {purpose}
+
+## Directory Structure
+
+```
+{SERVICE_NAME}/
+├── src/                  # Source code
+│   ├── components/       # (if applicable)
+│   ├── lib/              # Utilities
+│   ├── api/              # API routes
+│   └── ...
+├── public/               # Static assets (if web)
+├── tests/                # Test files
+├── .jfl/                 # JFL service agent files
+├── knowledge/            # Service documentation
+└── package.json          # Dependencies
+```
+
+## Key Components
+
+### {Component 1}
+- **Purpose:** What it does
+- **Location:** `src/path/to/component`
+- **Dependencies:** What it depends on
+- **Used By:** What uses it
+
+### {Component 2}
+- **Purpose:** What it does
+- **Location:** `src/path/to/component`
+- **Dependencies:** What it depends on
+- **Used By:** What uses it
+
+## Data Flow
+
+```
+{Describe how data flows through the service}
+
+User Request
+    ↓
+{Component A}
+    ↓
+{Component B}
+    ↓
+Response
+```
+
+## Configuration
+
+**Environment Variables:**
+| Variable | Purpose | Default | Required |
+|----------|---------|---------|----------|
+| {VAR_NAME} | ... | ... | Yes/No |
+
+**Config Files:**
+- `{config-file}`: {purpose}
+
+## Build & Development
+
+**Install dependencies:**
+```bash
+{install command}
+```
+
+**Development mode:**
+```bash
+{dev command}
+```
+
+**Build:**
+```bash
+{build command}
+```
+
+**Test:**
+```bash
+{test command}
+```
+
+## Integration Points
+
+### With {Other Service}
+- **Purpose:** Why we integrate
+- **Method:** HTTP API, event bus, shared DB, etc.
+- **Data Exchanged:** What data flows between services
+
+## Patterns & Conventions
+
+- **Code Style:** {linter, formatter}
+- **Naming:** {conventions}
+- **Error Handling:** {approach}
+- **Logging:** {approach}
+
+## Known Issues
+
+- {Issue 1}: {workaround if any}
+- {Issue 2}: {workaround if any}
+
+## Future Improvements
+
+- {Improvement 1}
+- {Improvement 2}
+
+## Last Updated
+
+{date}

package/template/templates/service-agent/knowledge/DEPLOYMENT.md

@@ -0,0 +1,199 @@
+# {SERVICE_NAME} - Deployment Guide
+
+## Deployment Target
+
+**Platform:** {Vercel, Fly.io, local, etc.}
+**Environment:** {production, staging, development}
+**URL:** {production URL if applicable}
+
+## Prerequisites
+
+- [ ] {Prerequisite 1}
+- [ ] {Prerequisite 2}
+- [ ] Access credentials configured
+- [ ] Environment variables set
+
+## Deployment Commands
+
+### Deploy to Production
+
+```bash
+{deployment command}
+```
+
+### Deploy to Staging
+
+```bash
+{staging deployment command if different}
+```
+
+### Rollback
+
+```bash
+{rollback command}
+```
+
+## Environment Variables
+
+Configure these before deploying:
+
+```bash
+# Required
+export {VAR1}="..."
+export {VAR2}="..."
+
+# Optional
+export {VAR3}="..."
+```
+
+**Where to set:**
+- Production: {where env vars are configured}
+- Staging: {where env vars are configured}
+- Development: `.env.local`
+
+## Pre-Deployment Checklist
+
+- [ ] Tests passing: `{test command}`
+- [ ] Build succeeds: `{build command}`
+- [ ] Environment variables verified
+- [ ] Dependencies up to date
+- [ ] Breaking changes documented
+- [ ] Database migrations applied (if applicable)
+
+## Post-Deployment Verification
+
+```bash
+# Health check
+curl {health-check-url}
+
+# Smoke test
+{smoke test commands}
+```
+
+## Service Control
+
+### Start Service
+
+```bash
+{start command}
+```
+
+### Stop Service
+
+```bash
+{stop command}
+```
+
+### Restart Service
+
+```bash
+{restart command}
+```
+
+### Check Status
+
+```bash
+{status check command}
+```
+
+### View Logs
+
+```bash
+{log command}
+```
+
+## Monitoring
+
+**Health Check URL:** {URL or method}
+**Logs:** {where logs are}
+**Metrics:** {where metrics are tracked}
+
+## Troubleshooting
+
+### Service Won't Start
+
+1. Check logs: `{log command}`
+2. Verify environment variables
+3. Check port availability
+4. Verify dependencies installed
+
+### Deployment Failed
+
+1. Check deployment logs
+2. Verify credentials
+3. Check for build errors
+4. Verify platform status
+
+### Performance Issues
+
+1. Check resource usage
+2. Review recent changes
+3. Check dependency services
+4. Review logs for errors
+
+## Rollback Procedure
+
+If deployment causes issues:
+
+```bash
+# 1. Rollback deployment
+{rollback command}
+
+# 2. Verify rollback succeeded
+{verification command}
+
+# 3. Investigate issue
+{investigation steps}
+```
+
+## Database Migrations (if applicable)
+
+**Run migration:**
+```bash
+{migration command}
+```
+
+**Rollback migration:**
+```bash
+{migration rollback command}
+```
+
+## Secrets Management
+
+**Where secrets are stored:** {secrets location}
+
+**Update secret:**
+```bash
+{secret update command}
+```
+
+## Common Operations
+
+### Update Dependencies
+
+```bash
+{dependency update command}
+npm audit fix  # or equivalent
+{test command}
+```
+
+### Clear Cache
+
+```bash
+{cache clear command if applicable}
+```
+
+### Database Backup (if applicable)
+
+```bash
+{backup command}
+```
+
+## Emergency Contacts
+
+- **Platform Support:** {contact info}
+- **On-Call:** {contact info}
+
+## Last Updated
+
+{date}