achira-wf 3.1.0

package/.agent/workflows/debug.md

@@ -0,0 +1,103 @@
+---
+description: Debugging command. Activates DEBUG mode for systematic problem investigation.
+---
+
+# /debug - Systematic Problem Investigation
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command activates DEBUG mode for systematic investigation of issues, errors, or unexpected behavior.
+
+---
+
+## Behavior
+
+When `/debug` is triggered:
+
+1. **Gather information**
+   - Error message
+   - Reproduction steps
+   - Expected vs actual behavior
+   - Recent changes
+
+2. **Form hypotheses**
+   - List possible causes
+   - Order by likelihood
+
+3. **Investigate systematically**
+   - Test each hypothesis
+   - Check logs, data flow
+   - Use elimination method
+
+4. **Fix and prevent**
+   - Apply fix
+   - Explain root cause
+   - Add prevention measures
+
+---
+
+## Output Format
+
+```markdown
+## 🔍 Debug: [Issue]
+
+### 1. Symptom
+[What's happening]
+
+### 2. Information Gathered
+- Error: `[error message]`
+- File: `[filepath]`
+- Line: [line number]
+
+### 3. Hypotheses
+1. ❓ [Most likely cause]
+2. ❓ [Second possibility]
+3. ❓ [Less likely cause]
+
+### 4. Investigation
+
+**Testing hypothesis 1:**
+[What I checked] → [Result]
+
+**Testing hypothesis 2:**
+[What I checked] → [Result]
+
+### 5. Root Cause
+🎯 **[Explanation of why this happened]**
+
+### 6. Fix
+```[language]
+// Before
+[broken code]
+
+// After
+[fixed code]
+```
+
+### 7. Prevention
+🛡️ [How to prevent this in the future]
+```
+
+---
+
+## Examples
+
+```
+/debug login not working
+/debug API returns 500
+/debug form doesn't submit
+/debug data not saving
+```
+
+---
+
+## Key Principles
+
+- **Ask before assuming** - get full error context
+- **Test hypotheses** - don't guess randomly
+- **Explain why** - not just what to fix
+- **Prevent recurrence** - add tests, validation

package/.agent/workflows/deploy.md

@@ -0,0 +1,176 @@
+---
+description: Deployment command for production releases. Pre-flight checks and deployment execution.
+---
+
+# /deploy - Production Deployment
+
+$ARGUMENTS
+
+---
+
+## Purpose
+
+This command handles production deployment with pre-flight checks, deployment execution, and verification.
+
+---
+
+## Sub-commands
+
+```
+/deploy            - Interactive deployment wizard
+/deploy check      - Run pre-deployment checks only
+/deploy preview    - Deploy to preview/staging
+/deploy production - Deploy to production
+/deploy rollback   - Rollback to previous version
+```
+
+---
+
+## Pre-Deployment Checklist
+
+Before any deployment:
+
+```markdown
+## 🚀 Pre-Deploy Checklist
+
+### Code Quality
+- [ ] No TypeScript errors (`npx tsc --noEmit`)
+- [ ] ESLint passing (`npx eslint .`)
+- [ ] All tests passing (`npm test`)
+
+### Security
+- [ ] No hardcoded secrets
+- [ ] Environment variables documented
+- [ ] Dependencies audited (`npm audit`)
+
+### Performance
+- [ ] Bundle size acceptable
+- [ ] No console.log statements
+- [ ] Images optimized
+
+### Documentation
+- [ ] README updated
+- [ ] CHANGELOG updated
+- [ ] API docs current
+
+### Ready to deploy? (y/n)
+```
+
+---
+
+## Deployment Flow
+
+```
+┌─────────────────┐
+│  /deploy        │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Pre-flight     │
+│  checks         │
+└────────┬────────┘
+         │
+    Pass? ──No──► Fix issues
+         │
+        Yes
+         │
+         ▼
+┌─────────────────┐
+│  Build          │
+│  application    │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Deploy to      │
+│  platform       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  Health check   │
+│  & verify       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  ✅ Complete    │
+└─────────────────┘
+```
+
+---
+
+## Output Format
+
+### Successful Deploy
+
+```markdown
+## 🚀 Deployment Complete
+
+### Summary
+- **Version:** v1.2.3
+- **Environment:** production
+- **Duration:** 47 seconds
+- **Platform:** Vercel
+
+### URLs
+- 🌐 Production: https://app.example.com
+- 📊 Dashboard: https://vercel.com/project
+
+### What Changed
+- Added user profile feature
+- Fixed login bug
+- Updated dependencies
+
+### Health Check
+✅ API responding (200 OK)
+✅ Database connected
+✅ All services healthy
+```
+
+### Failed Deploy
+
+```markdown
+## ❌ Deployment Failed
+
+### Error
+Build failed at step: TypeScript compilation
+
+### Details
+```
+error TS2345: Argument of type 'string' is not assignable...
+```
+
+### Resolution
+1. Fix TypeScript error in `src/services/user.ts:45`
+2. Run `npm run build` locally to verify
+3. Try `/deploy` again
+
+### Rollback Available
+Previous version (v1.2.2) is still active.
+Run `/deploy rollback` if needed.
+```
+
+---
+
+## Platform Support
+
+| Platform | Command | Notes |
+|----------|---------|-------|
+| Vercel | `vercel --prod` | Auto-detected for Next.js |
+| Railway | `railway up` | Needs Railway CLI |
+| Fly.io | `fly deploy` | Needs flyctl |
+| Docker | `docker compose up -d` | For self-hosted |
+
+---
+
+## Examples
+
+```
+/deploy
+/deploy check
+/deploy preview
+/deploy production --skip-tests
+/deploy rollback
+```

package/.agent/workflows/enhance.md

@@ -0,0 +1,63 @@
+---
+description: Add or update features in existing application. Used for iterative development.
+---
+
+# /enhance - Update Application
+
+$ARGUMENTS
+
+---
+
+## Task
+
+This command adds features or makes updates to existing application.
+
+### Steps:
+
+1. **Understand Current State**
+   - Load project state with `python .achira/scripts/session_manager.py info`
+   - Understand existing features, tech stack
+
+2. **Plan Changes**
+   - Determine what will be added/changed
+   - Detect affected files
+   - Check dependencies
+
+3. **Present Plan to User** (for major changes)
+   ```
+   "To add admin panel:
+   - I'll create 15 new files
+   - Update 8 files
+   - Takes ~10 minutes
+   
+   Should I start?"
+   ```
+
+4. **Apply**
+   - Call relevant agents
+   - Make changes
+   - Test
+
+5. **Update Preview**
+   - Hot reload or restart
+
+---
+
+## Usage Examples
+
+```
+/enhance add dark mode
+/enhance build admin panel
+/enhance integrate payment system
+/enhance add search feature
+/enhance edit profile page
+/enhance make responsive
+```
+
+---
+
+## Caution
+
+- Get approval for major changes
+- Warn on conflicting requests (e.g., "use Firebase" when project uses PostgreSQL)
+- Commit each change with git

package/.agent/workflows/html+js+css.md

@@ -0,0 +1,363 @@
+---
+description: Scaffold a clean, scalable vanilla HTML + CSS + JavaScript project with clear separation of concerns.
+---
+
+// turbo-all
+
+## Philosophy
+
+This workflow enforces a strict separation between structure, style, and behavior.
+
+- **HTML** = Structure only. No inline styles, no inline scripts.
+- **CSS** = Styling only. Split by concern: globals, layout, page-specific.
+- **JS** = Behavior only. Modular ES modules — one entry point, shared utils.
+
+---
+
+## 1. Create the Project Structure
+
+```
+mkdir src
+mkdir src/pages
+mkdir src/styles
+mkdir src/scripts
+mkdir src/components
+mkdir public
+```
+
+Final structure:
+
+```
+project/
+├── public/
+├── src/
+│   ├── pages/
+│   │   └── index.html
+│   ├── styles/
+│   │   ├── globals.css
+│   │   ├── layout.css
+│   │   └── index.css
+│   ├── scripts/
+│   │   ├── main.js
+│   │   └── utils.js
+│   └── components/
+├── jsconfig.json
+├── .gitignore
+└── README.md
+```
+
+---
+
+## 2. Create `src/pages/index.html`
+
+The entry point. Links all CSS and the JS module. No styles or scripts inline.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Project</title>
+
+    <!-- Global reset + variables -->
+    <link rel="stylesheet" href="../styles/globals.css" />
+    <!-- Reusable layout utilities -->
+    <link rel="stylesheet" href="../styles/layout.css" />
+    <!-- Page-specific styles -->
+    <link rel="stylesheet" href="../styles/index.css" />
+  </head>
+  <body>
+    <div class="container">
+      <h1>Hello World</h1>
+    </div>
+
+    <!-- module: enables import/export -->
+    <script type="module" src="../scripts/main.js"></script>
+  </body>
+</html>
+```
+
+---
+
+## 3. Create `src/styles/globals.css`
+
+The single source of truth for CSS variables and the global reset.
+No component-specific styles go here.
+
+```css
+/* Modern Reset */
+*,
+*::before,
+*::after {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+html {
+  font-size: 16px;
+  scroll-behavior: smooth;
+}
+
+img,
+picture,
+video,
+canvas,
+svg {
+  display: block;
+  max-width: 100%;
+}
+
+button {
+  cursor: pointer;
+}
+
+/* Design Tokens */
+:root {
+  --color-primary: #6366f1;
+  --color-bg: #ffffff;
+  --color-text: #111827;
+  --color-subtle: #6b7280;
+  --font-sans: system-ui, -apple-system, sans-serif;
+  --transition-default: all 0.2s ease;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #0f172a;
+    --color-text: #f8fafc;
+  }
+}
+
+body {
+  font-family: var(--font-sans);
+  background-color: var(--color-bg);
+  color: var(--color-text);
+  line-height: 1.6;
+}
+```
+
+---
+
+## 4. Create `src/styles/layout.css`
+
+Shared structural utilities across all pages. Not page-specific.
+
+```css
+/* Centered content wrapper */
+.container {
+  width: min(1100px, 90%);
+  margin: 0 auto;
+  padding: 2rem 0;
+}
+
+/* Utility layout classes */
+.flex {
+  display: flex;
+}
+.flex-col {
+  flex-direction: column;
+}
+.flex-center {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.grid {
+  display: grid;
+}
+.grid-2 {
+  grid-template-columns: repeat(2, 1fr);
+  gap: 1.5rem;
+}
+.grid-3 {
+  grid-template-columns: repeat(3, 1fr);
+  gap: 1.5rem;
+}
+```
+
+---
+
+## 5. Create `src/styles/index.css`
+
+Styles for the index page only. Each page gets its own file.
+
+```css
+/* index page styles */
+h1 {
+  color: var(--color-primary);
+  font-size: 2.5rem;
+  margin-bottom: 1rem;
+}
+```
+
+---
+
+## 6. Create `src/scripts/utils.js`
+
+Pure, reusable helper functions. No DOM access. No side effects.
+
+```javascript
+/**
+ * One-call app initializer. Add further calls here as the app grows.
+ */
+export function initApp() {
+  console.log("[App] Initialized");
+}
+
+/**
+ * Convenience wrapper: returns a single element or null.
+ * @param {string} selector
+ * @returns {Element|null}
+ */
+export function qs(selector) {
+  return document.querySelector(selector);
+}
+
+/**
+ * Convenience wrapper: returns a NodeList.
+ * @param {string} selector
+ * @returns {NodeList}
+ */
+export function qsAll(selector) {
+  return document.querySelectorAll(selector);
+}
+```
+
+---
+
+## 7. Create `src/scripts/main.js`
+
+The single JS entry point. Imports utils, hooks into `DOMContentLoaded`.
+Page-specific logic starts here, but delegates to modules.
+
+```javascript
+import { initApp } from "./utils.js";
+
+document.addEventListener("DOMContentLoaded", () => {
+  initApp();
+});
+```
+
+---
+
+## 8. Create `jsconfig.json`
+
+Enable IntelliSense, type-checking via JSDoc, and module resolution in VS Code.
+
+```json
+{
+  "compilerOptions": {
+    "checkJs": true,
+    "moduleResolution": "node",
+    "target": "ES2020",
+    "module": "ES2020"
+  },
+  "include": ["src/**/*.js"],
+  "exclude": ["node_modules"]
+}
+```
+
+---
+
+## 9. Create `.gitignore`
+
+```
+node_modules/
+dist/
+.DS_Store
+*.log
+.env
+.env.local
+```
+
+---
+
+## 10. Create `README.md`
+
+```markdown
+# Project Name
+
+A clean HTML + CSS + JS project.
+
+## Structure
+
+| Folder            | Purpose                                                                             |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| `src/pages/`      | HTML entry points — one file per page                                               |
+| `src/styles/`     | `globals.css` (design tokens), `layout.css` (utilities), `page.css` (page-specific) |
+| `src/scripts/`    | `main.js` (entry), `utils.js` (shared helpers)                                      |
+| `src/components/` | Reusable HTML snippets (loaded/injected via JS if needed)                           |
+| `public/`         | Static assets: images, fonts, favicon                                               |
+
+## Rules
+
+- No inline CSS
+- No inline scripts
+- Use CSS variables from `globals.css`
+- Use `type="module"` on all script tags
+- One CSS file per page (mirroring `src/pages/`)
+
+## Dev Server
+```
+
+npm run dev
+
+```
+
+```
+
+---
+
+## 11. Initialize npm and Install Dev Server
+
+```
+npm init -y
+npm install -D vite
+```
+
+Add to `package.json`:
+
+```json
+"scripts": {
+  "dev": "vite src/pages --port=3000 --open",
+  "build": "vite build",
+  "preview": "vite preview"
+}
+```
+
+Run:
+
+```
+npm run dev
+```
+
+---
+
+## Scaling Rules
+
+As the project grows, follow this pattern:
+
+```
+src/
+├── pages/
+│   ├── index.html         ← each page has its own HTML
+│   ├── about.html
+│   └── contact.html
+├── styles/
+│   ├── globals.css        ← shared always
+│   ├── layout.css         ← shared always
+│   ├── index.css          ← page-specific
+│   ├── about.css
+│   └── contact.css
+├── scripts/
+│   ├── main.js            ← one per page (or shared entry + conditionals)
+│   └── utils.js
+└── components/            ← HTML snippets injected via fetch() or JS
+```
+
+- Never let `globals.css` accumulate page-specific rules.
+- Never use `<style>` tags inside HTML files.
+- Never write logic inside event listeners — delegate to named functions.