additions

AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md
+
+This repository is a Node.js backend template maintained for human developers and Codex.
+
+## Read this first
+
+1. `README.md`
+2. `docs/README.md`
+3. `docs/ARCHITECTURE.md`
+4. `docs/WORKFLOW.md`
+5. `docs/QUALITY.md`
+6. Active plan files under `docs/exec-plans/active/`
+
+## Operating rules
+
+- Keep changes small and verifiable.
+- Do not delete existing template features unless the task explicitly requires it.
+- Prefer extending existing patterns over introducing parallel patterns.
+- Read a file before changing it.
+- Update docs when behavior, architecture, or workflow changes.
+- Run verification before declaring work done.
+
+## Definition of done
+
+A task is complete only when:
+
+- implementation is present,
+- docs are updated when needed,
+- `npm run verify` passes, or failures are explained precisely,
+- plan file status is updated if the task used an execution plan.
+
+## Where things live
+
+- Product and engineering guidance: `docs/`
+- Active execution plans: `docs/exec-plans/active/`
+- Completed execution plans: `docs/exec-plans/completed/`
+- Codex project config: `.codex/`
+- Worktree/bootstrap helpers: `scripts/`
+
+## Command preferences
+
+- Use `npm run verify` for the standard local verification flow.
+- Use `npm run worktree:bootstrap` in new worktrees.
+- Use `npm run plan:new -- --slug=<slug> --title="<title>"` to create a new execution plan.
+
+## Constraints
+
+- Preserve the existing non-agentic template structure and behavior.
+- Additive improvements are preferred to replacements.

README.md

@@ -5,6 +5,30 @@ Production-ready Node.js/Express.js backend template for building scalable, secu
 **Maintained by:** Codebucket Solutions Pvt. Ltd.
 
 📚 **Documentation**: See [`docs/`](./docs) for detailed usage guides.
+Workflow engine guide: [`service/v1/workflow-engine/README.md`](./service/v1/workflow-engine/README.md)
+
+## 🤖 Codex / Agent-Ready Additions
+
+This template now includes an additive repository operating layer for Codex and other coding agents while preserving the existing backend template structure.
+
+### Added capabilities
+
+- `AGENTS.md` for repo-level operating guidance
+- `.codex/config.toml` for trusted project-scoped Codex defaults
+- `docs/ARCHITECTURE.md`, `docs/WORKFLOW.md`, `docs/QUALITY.md`, `docs/SECURITY.md`, and `docs/RELIABILITY.md`
+- execution plans under `docs/exec-plans/`
+- deterministic worktree bootstrap script
+- repository verification and quality scoring scripts
+- CI workflow for baseline enforcement
+- Codex app setup guide in `docs/CODEX_APP_SETUP.md`
+
+### Recommended commands
+
+```bash
+npm run worktree:bootstrap
+npm run verify
+npm run plan:new -- --slug=my-task --title="My Task"
+```
 
 ---
 
@@ -60,7 +84,7 @@ node-template/
 ├── routes/                    # API routes (versioned)
 │   └── v1/
 ├── service/                   # Business logic layer
-│   └── v1/
+│   └── v1/                    # Includes workflow/assignment orchestration services
 ├── utils/                     # Utility functions
 ├── plop-templates/            # Code generation templates
 ├── app.js                     # Express app configuration
@@ -195,6 +219,15 @@ npm run plop
 - **Virus scanning** support (ClamAV)
 - **Upload rate limiting**
 
+### 10. **Workflow & Assignment Engine** 🔄
+
+- **Sequelize-backed assignment rules** for auto-assignment and reassignment
+- **Workflow action timeline** for application-level state transitions
+- **Escalation matrix** for stage/action-driven routing and auto escalation
+- **Resolver-based assignee lookup** for context-sensitive assignment flows
+
+📖 **[View workflow engine guide →](./service/v1/workflow-engine/README.md)**
+
 ### 10. **Email Notifications** 📧
 
 - **Nodemailer** with Zoho SMTP
@@ -246,12 +279,29 @@ NODE_ENV=development
 # JWT
 JWT_PRIVATE_KEY=your_secret_key
 
-# Email (Zoho)
+# Email
+EMAIL_TRANSPORT=SMTP
 EMAIL_HOST=smtp.zoho.in
 EMAIL_PORT=465
 EMAIL_USER=your_email@example.com
 EMAIL_PASSWORD=your_email_password
 
+# Mail server transport (used when EMAIL_TRANSPORT is not SMTP)
+MAILSERVER_URL=
+MAILSERVER_SENDERID=
+MAILSERVER_ACCESSTOKEN=
+
+# SMS
+SMS_TRANSPORT=GOVT
+SMS_SERVER_URL=
+SMS_SENDER_ID=
+SMS_ACCESS_TOKEN=
+PASSWORDSMS=
+ENDPOINT=
+KEY=
+SENDERID=
+USERNAMESMS=
+
 # Redis (Production Rate Limiting)
 REDIS_HOST=127.0.0.1
 REDIS_PORT=6379
@@ -506,3 +556,7 @@ PORT=9001
 For internal support, contact: **team@thecodebucket.com**
 
 Repository: https://github.com/Codebucket-Solutions/node-template
+
+## Symphony support
+
+This template now includes a root `WORKFLOW.md`, `scripts/symphony-bootstrap.sh`, and `docs/SYMPHONY_SETUP.md` so it can be used with OpenAI Symphony in addition to Codex worktree workflows.

WORKFLOW.md

@@ -0,0 +1,70 @@
+---
+tracker:
+    kind: linear
+    api_key: $LINEAR_API_KEY
+    project_slug: "replace-with-your-linear-project-slug"
+workspace:
+    root: $SYMPHONY_WORKSPACE_ROOT
+hooks:
+    after_create: |
+        git clone --depth 1 "$SOURCE_REPO_URL" .
+        bash scripts/symphony-bootstrap.sh
+agent:
+    max_concurrent_agents: 5
+    max_turns: 20
+codex:
+    command: "${CODEX_BIN:-codex} app-server"
+    # approval_policy values depend on your Codex app-server version.
+    # Common values documented by OpenAI include: untrusted, on-failure, on-request, never.
+    approval_policy: on-request
+    thread_sandbox: workspace-write
+server:
+    port: 4100
+---
+
+# Symphony workflow contract
+
+You are working on a tracked issue in this repository.
+
+## Read before making changes
+
+1. `AGENTS.md`
+2. `README.md`
+3. `docs/README.md`
+4. `docs/ARCHITECTURE.md`
+5. `docs/WORKFLOW.md`
+6. `docs/QUALITY.md`
+7. The most relevant files under `docs/exec-plans/active/`
+
+## Repository expectations
+
+- Preserve all existing template behavior unless the issue explicitly requires otherwise.
+- Prefer additive changes over replacements.
+- Keep changes small, verifiable, and easy to review.
+- Read files before editing them.
+- Update docs when architecture, behavior, workflow, or developer setup changes.
+- Run repository verification before finishing.
+
+## Issue handling
+
+- Treat the Linear issue identifier, title, and body as the task contract.
+- If the issue is broad, create or update an execution plan under `docs/exec-plans/active/` before making large changes.
+- If the issue is underspecified, choose the safest minimal implementation that still resolves the request.
+
+## Verification
+
+Before declaring the issue done, run:
+
+```sh
+npm run verify
+```
+
+If verification fails, either fix the issue or report the failure precisely with the command output and a concise explanation.
+
+## Completion checklist
+
+- Implementation completed.
+- Docs updated when needed.
+- Plan updated when used.
+- Verification run.
+- Final summary includes files changed, verification status, and any follow-up work.

bin/www

@@ -10,38 +10,39 @@ const cpu = require("os").cpus().length;
 const app = require("../app");
 const debug = require("debug")("sidebrain:server");
 const http = require("http");
-const port = normalizePort(process.env.PORT || "3000");
+const port = normalizePort(process.env.PORT || "8080");
 let server;
+const initMaster = require("../init");
 
 /**
  * Get port from environment and store in Express.
  */
 
-if (cluster.isMaster) {
-	// Master initialization (DB, Cron, etc.)
-	const initMaster = require("../init");
-	initMaster()
-		.then(() => {
-			console.log("✔ Master initialization completed");
-		})
-		.catch(err => {
-			console.error("❌ Master initialization failed:", err);
-			process.exit(1);
-		});
+async function runMaster() {
+	console.log("Starting master initialization");
+	await initMaster();
+	console.log("Master-only services initialized");
 
-	// Worker
 	const workers =
-		process.env.NODE_ENV === "stage" || process.env.NODE_ENV === "development"
+		process.env.WEB_CONCURRENCY ??
+		(process.env.NODE_ENV === "stage" || process.env.NODE_ENV === "development"
 			? 1
-			: Math.max(1, cpu);
-	for (let i = 0; i < workers; i++) {
-		console.log("Forking worker", i + 1, "of", workers);
+			: Math.max(1, cpu));
+
+	for (let i = 0; i < Number(workers); i++) {
+		console.log("Forking worker", i + 1, "of", Number(workers));
 		cluster.fork();
 	}
+}
+
+if (cluster.isPrimary) {
+	runMaster().catch(err => {
+		console.error("Master initialization failed:", err);
+		process.exit(1);
+	});
 
-	// Auto-restart worker on crash
 	cluster.on("exit", worker => {
-		console.log(`Worker ${worker.process.pid} died → restarting…`);
+		console.log(`Worker ${worker.process.pid} died, restarting`);
 		cluster.fork();
 	});
 } else {

docker-compose.yml

@@ -1,15 +1,15 @@
 services:
-  node-template:
-    image: harbor.internal.codebuckets.in/node-template/stage
-    container_name: node-template
-    restart: unless-stopped
-    ports:
-      - "127.0.0.1:25000:3000"
-    networks:
-      - database_network
-    env_file:
-      - /home/empty.env
+    node-template:
+        image: harbor.internal.codebuckets.in/node-template/stage
+        container_name: node-template
+        restart: unless-stopped
+        ports:
+            - "127.0.0.1:25000:3000"
+        networks:
+            - database_network
+        env_file:
+            - /home/empty.env
 
 networks:
-  database_network:
-    external: true
+    database_network:
+        external: true

docs/ARCHITECTURE.md

@@ -0,0 +1,30 @@
+# Architecture
+
+This repository is an additive enhancement of the existing Node.js backend template. The original application structure remains the primary runtime architecture.
+
+## Runtime architecture
+
+```text
+Request -> Routes -> Middleware -> Controllers -> Services -> Models -> Database
+```
+
+## Harness-engineering overlay
+
+The repository also includes a repo-native operating layer designed for Codex and other coding agents:
+
+- `AGENTS.md`: short operational contract for agents.
+- `docs/`: versioned system of record for architecture, workflow, quality, reliability, and security.
+- `docs/exec-plans/`: checked-in execution plans for task tracking.
+- `.codex/`: project-scoped Codex configuration.
+- `scripts/`: deterministic setup, verification, and plan-generation helpers.
+- `.github/workflows/`: mechanical enforcement in CI.
+
+## Architectural principle
+
+Application code and repo operations are separate concerns:
+
+- App code continues to live in `app.js`, `routes/`, `middleware/`, `models/`, `helper/`, and `utils/`.
+- Stateful business workflows can be implemented in `service/v1/` with Sequelize models backing assignment, workflow action, and escalation rules.
+- Agent operating guidance lives in repo-root docs and scripts.
+
+This keeps the backend template usable for normal development while making the repository legible to Codex.