feat: Structured Agent Execution Event Log with ContextItem System

.claude/skills/spec-coding/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: spec-coding
+description: Use for Nexent feature work, architecture changes, database/API changes, multi-file refactors, or any implementation that should be driven by SPEC documentation. Enforces documentation-first development through the Nexent Development SPECs Wiki: organize by implementation status, then feature scope, then lifecycle documents; update requirements, functional design, technical design, and development plan before coding.
+license: Complete terms in LICENSE.txt
+---
+
+# Spec Coding
+
+Use this skill for Nexent coding work that changes product behavior, architecture, data models, APIs, persistence, runtime flows, or multiple modules. The goal is controlled implementation: document first, develop from the approved docs, and keep the Wiki as the source of truth.
+
+## Source of Truth
+
+Use the Feishu Wiki named `Nexent Development SPECs`. URL: https://dcnvjn24oieg.feishu.cn/wiki/KyU6wFj3siGJ1WkWlu8cTHgwnYb
+
+Top-level organization is by implementation status:
+
+```text
+00 - Wiki Governance and Reading Guide
+10 - Proposed Specs
+20 - In Development Specs
+30 - Implemented Specs
+40 - Paused or Superseded Specs
+90 - Templates and Standards
+```
+
+Inside each status section, organize by feature scope. Inside each feature scope, use lifecycle documents:
+
+```text
+<Feature Scope>
+├── 00 - Requirement Analysis
+├── 01 - Functional Design
+├── 02 - Technical Design
+└── 03 - Development Plan
+```
+
+If a parent page has children, its body may include a `Quick Access` table, but only for direct children (depth 1). Every entry in `Quick Access` must be a clickable link to the child page. Do not maintain a global directory in page bodies; the Wiki UI already provides that.
+
+## Mandatory Workflow
+
+Before writing code:
+
+1. Identify the feature scope and current implementation status.
+2. Locate or create the feature scope under the correct status section.
+3. Ensure these lifecycle pages exist:
+   - `00 - Requirement Analysis`
+   - `01 - Functional Design`
+   - `02 - Technical Design`
+   - `03 - Development Plan`
+4. Read the relevant lifecycle pages before editing code.
+5. If the docs are missing or stale, update the Wiki first.
+6. Only implement code that is traceable to the approved lifecycle docs.
+
+During coding:
+
+- Keep the implementation aligned with the `03 - Development Plan` PR/phase breakdown.
+- If code discoveries invalidate the docs, stop broad implementation and update the relevant lifecycle page first.
+- Keep acceptance criteria, tests, migrations, and compatibility requirements synchronized with the docs.
+
+After coding:
+
+- Update the relevant lifecycle page with implementation notes only when they change the plan, design, or acceptance criteria.
+- Move the feature scope between status sections when its lifecycle status changes:
+  - `Proposed Specs` -> `In Development Specs` when implementation starts.
+  - `In Development Specs` -> `Implemented Specs` after implementation and acceptance.
+  - Any active status -> `Paused or Superseded Specs` when paused, abandoned, or replaced.
+
+## Lifecycle Page Responsibilities
+
+`00 - Requirement Analysis`:
+
+- Problem statement
+- Goals and non-goals
+- User or system impact
+- Constraints
+- Risks
+
+`01 - Functional Design`:
+
+- User-visible or system-visible behavior
+- Capability boundaries
+- Functional decomposition
+- Error, empty, compatibility, and migration behavior where relevant
+
+`02 - Technical Design`:
+
+- Architecture
+- Interfaces and contracts
+- Data models and schema changes
+- Runtime integration points
+- Backward compatibility strategy
+
+`03 - Development Plan`:
+
+- Phase and PR breakdown
+- File/module ownership
+- Acceptance criteria
+- Test plan
+- Rollout and fallback notes
+
+## Nexent-Specific Checks
+
+For backend work, preserve the app/service/const layer boundaries described in `AGENTS.md`.
+
+For environment variables, keep `backend/consts/const.py` as the single source of truth. SDK code must not read environment variables directly.
+
+For DB schema changes, update all required locations:
+
+- versioned migration under `docker/sql/*.sql` or the project migration location in use
+- Docker Compose fresh deploy init SQL
+- K8s fresh deploy init SQL
+- `APP_VERSION` if the project versioning rule requires it
+
+For tests, follow the project pytest conventions and add focused coverage matching the documented acceptance criteria.
+
+## When Documentation Can Be Lightweight
+
+Tiny mechanical fixes may use a short existing scope note instead of a full lifecycle set only when all are true:
+
+- The change is single-purpose and low risk.
+- No API, DB, runtime contract, or user-visible behavior changes.
+- No cross-module coordination is needed.
+- The user explicitly wants a small fix.
+
+Even then, mention the relevant existing SPEC or explain why no SPEC update was needed.
+

.gitignore

@@ -85,3 +85,7 @@ _doc/
 /deploy/env/.env.bak
 
 agent_repository_frontend
+
+.tokensave
+
+.playwright-mcp/

AGENTS.md

@@ -24,6 +24,12 @@ Usage notes:
 
 <available_skills>
 
+<skill>
+<name>spec-coding</name>
+<description>Use for Nexent feature work, architecture changes, database/API changes, multi-file refactors, or any implementation that should be driven by SPEC documentation. Enforces documentation-first development through the Nexent Development SPECs Wiki: organize by implementation status, then feature scope, then lifecycle documents; update requirements, functional design, technical design, and development plan before coding.</description>
+<location>project</location>
+</skill>
+
 <skill>
 <name>prompts-writing</name>
 <description>Create, refine, and optimize high-quality YAML prompts for AI assistants. Use when working with prompt templates, system prompts, agent prompts, or any prompt engineering tasks. Provides structure guidelines, template patterns, and quality standards for YAML-based prompts.</description>
@@ -53,6 +59,31 @@ Nexent is a zero-code platform for auto-generating AI agents. Monorepo with:
 
 ---
 
+## SPEC Coding Workflow (Mandatory)
+
+For any Nexent feature work, architecture change, database/API change, multi-file refactor, runtime behavior change, or other implementation that can affect product behavior, **invoke and follow the `spec-coding` skill before coding**.
+
+Development must be documentation-first:
+- Use the Feishu Wiki `Nexent Development SPECs` as the source of truth.
+- Organize SPEC documents by implementation status first, then feature Scope, then lifecycle document type.
+- The expected lifecycle pages are `00 - Requirement Analysis`, `01 - Functional Design`, `02 - Technical Design`, and `03 - Development Plan`.
+- Read the relevant lifecycle pages before editing code.
+- If required SPEC pages are missing or stale, update the Wiki first, then implement.
+- Code changes must trace back to the documented requirements, design, development plan, and acceptance criteria.
+- If implementation discoveries invalidate the SPEC, update the relevant lifecycle page before continuing broad code changes.
+
+Only tiny mechanical fixes may skip a full SPEC update, and only when they do not change API, DB schema, runtime contracts, cross-module behavior, or user-visible behavior. In that case, state why no SPEC update was needed.
+
+Development must be test-verified against the documented acceptance criteria:
+- Unit tests should relact the acceptance criteria and edge cases from the SPEC.
+- Unit tests must reach 90% coverage for any new or modified module.
+- Integration tests must verify cross-module behavior and runtime flows.
+- For all frontend-affected changes, `playwright` must be used to verify user-visible behavior and acceptance criteria.
+- For all backend-affected changes, `curl` or `wget` must be used to verify API behavior and acceptance criteria.
+- For all SDK-affacted changes, when actual model calls are required to perform functional test, ask the user to provide one, and test with `LangFuse` to trace every step's input and output.
+
+---
+
 ## Developer Commands
 
 ### Backend (Python 3.11)
@@ -165,4 +196,4 @@ Existing instruction files with detailed rules:
 - `CLAUDE.md` - Backend architecture, env var management, app/service layer rules
 - `.cursor/rules/environment_variable.mdc` - Env var centralization
 - `.cursor/rules/pytest_unit_test_rules.mdc` - Testing patterns
-- `.cursor/rules/english_comments.mdc` - Comment language enforcement
+- `.cursor/rules/english_comments.mdc` - Comment language enforcement