How to Configure Agent Authority and Story-Driven Development Constitution Rules in aios-core

Configure Agent Authority by editing the authority table in /.aios-core/constitution.md and declaring matching exclusive_authority blocks in agent definitions, while Story-Driven Development requires creating valid story YAML files in docs/stories/{id}/story.yaml that pass the constitutional gate in dev-develop-story.md.

The aios-core framework from SynkraAI enforces a strict constitutional governance model where agents operate under defined authorities and development is strictly story-driven. Understanding how to configure these Agent Authority and Story-Driven Development constitution rules in aios-core ensures your AI agents respect exclusive operational boundaries and only execute code against validated stories.

Where the Constitution Rules Live

The Synkra AIOS Constitution serves as the master source of truth for all governance rules. It resides in [/.aios-core/constitution.md](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/constitution.md) and defines two critical principles:

• Agent Authority (lines 30-50): Establishes exclusive rights for specific Git operations, versioning, and decision-making
• Story-Driven Development (lines 56-68): Mandates that no code may be written without a valid story containing acceptance criteria and tasks

These principles are enforced by constitutional gates implemented in specific task files and agent definitions throughout the repository.

Configuring Agent Authority

Updating the Constitutional Authority Table

Agent Authority rules are defined in a markdown table within constitution.md (lines 42-50). Each row maps an authority to its exclusive agent(s).

To add a new authority, edit the table:

| Autoridade               | Agente Exclusivo |
|--------------------------|------------------|
| git push                 | @devops          |
| PR creation              | @devops          |
| Release/Tag              | @devops          |
| Story creation           | @sm, @po         |
| Architecture decisions   | @architect       |   <!-- NEW -->
| Quality verdicts         | @qa              |

Commit this change to /.aios-core/constitution.md. The constitutional gate automatically references this table to validate agent permissions.

Declaring Exclusive Authority in Agent Definitions

Each agent must declare its exclusive_authority block in its definition file under /.aios-core/development/agents/<agent>.md (e.g., architect.md, devops.md).

For example, in /.aios-core/development/agents/architect.md:

exclusive_authority:
  note: 'CRITICAL: This is the ONLY agent authorized to make architecture decisions'
  rationale: 'Centralising architecture prevents conflicting designs'
  enforcement: 'Git hooks + AIOS gate checks'

The UnifiedActivationPipeline reads this YAML during agent activation and validates the exclusive_authority list against the Constitution at runtime.

Validating Authority with Pre-Push Gates

Run the quality-gate test to confirm new authorities are respected:

*pre-push   # runs all gates, including Agent Authority validation

If a non-authorized agent (e.g., @dev) attempts to execute a restricted operation like an architecture decision or git push, the gate aborts with BLOCK severity and prevents the action.

Configuring Story-Driven Development

Creating Valid Story Files

Story-Driven Development requires every story to exist as a YAML file under docs/stories/{storyId}/story.yaml. The constitutional gate in /.aios-core/development/tasks/dev-develop-story.md validates these fields:

# docs/stories/3.14/story.yaml

id: "3.14"
title: "Add GitHub release automation"
status: "Ready"                # must NOT be "Draft"

acceptance_criteria:
  - "Release tag created"
  - "Changelog generated"
tasks:
  - "Implement release script"

Required keys include id (string), title (string), status (cannot be "Draft"), acceptance_criteria (list), and tasks (list). Missing any field results in a BLOCK status from the gate.

Understanding the Constitutional Gate

The enforcement mechanism resides in [/.aios-core/development/tasks/dev-develop-story.md](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/dev-develop-story.md) at lines 92-106 under the Constitutional Gates section.

This gate performs four validations:

1. Story file exists at docs/stories/{storyId}/story.yaml
2. Status is not "Draft"
3. Acceptance criteria are present and non-empty
4. At least one task or sub-task is defined

If any check fails, the gate returns BLOCK severity and the *develop {storyId} command aborts immediately.

Running Story Development Tasks

To start development on a story, run:

*develop 3.14

This command triggers the constitutional gate first. Only after the story passes validation (status is "Ready", criteria exist, tasks defined) will the agent proceed with implementation.

To update a story, simply modify the YAML file (e.g., add more acceptance criteria) and commit. The gate always reads the latest file; no additional configuration is required.

Complete Workflow Example

Here is a complete workflow demonstrating both constitutional rules in action:

# 1️⃣ Verify story exists and is ready (Story-Driven Development gate)

*develop 3.14

# 2️⃣ Agent authority enforcement during development

#    - @dev writes code

#    - @architect decides on architecture (exclusive authority)

#    - @devops will later push the changes (exclusive git push authority)

# 3️⃣ Pre-push quality gate (includes both constitution checks)

*pre-push                    # runs lint, test, typecheck, CodeRabbit, and Agent Authority gates

# 4️⃣ Push (only @devops can execute)

*push                        # succeeds because the current agent is @devops

Common Pitfalls & How to Fix Them

Symptom	Cause (Constitution)	Fix
*develop aborts with "Story file not found"	Story-Driven Development gate cannot locate docs/stories/<id>/story.yaml	Create the YAML file in the correct path and commit
*push blocked by "Only @devops can git push"	Agent Authority gate detects a non-devops agent attempting a push	Switch to @devops (*activate devops) or delegate the push to the devops agent
Pre-push fails on "CRITICAL CodeRabbit issues"	Quality-First gate (not about authority or story)	Resolve the reported CodeRabbit issues, then rerun *pre-push

Summary

• The Synkra AIOS Constitution in /.aios-core/constitution.md defines Agent Authority (lines 30-50) and Story-Driven Development (lines 56-68) as non-negotiable principles.
• Agent Authority requires updating the constitutional table and declaring exclusive_authority blocks in agent definitions under /.aios-core/development/agents/.
• Story-Driven Development mandates YAML story files in docs/stories/{id}/story.yaml with required fields enforced by the gate in /.aios-core/development/tasks/dev-develop-story.md.
• Always run *pre-push to validate constitutional compliance before Git operations.

Frequently Asked Questions

What happens if an agent tries to execute an action outside its authority?

The Agent Authority constitutional gate detects the violation during the *pre-push check or when the agent attempts the action, aborting the operation with BLOCK severity. According to the implementation in /.aios-core/constitution.md lines 30-50, only agents listed in the authority table may execute their mapped operations.

Can I disable Story-Driven Development for quick fixes or hotfixes?

No. The Story-Driven Development principle defined in /.aios-core/constitution.md lines 56-68 is non-negotiable. The constitutional gate in /.aios-core/development/tasks/dev-develop-story.md (lines 92-106) will block any *develop command if a valid story file does not exist at docs/stories/{id}/story.yaml with status not equal to "Draft".

How do I add a new agent with exclusive authority?

First, add the agent and its authority to the table in /.aios-core/constitution.md (around lines 42-50). Then create or edit the agent definition file at /.aios-core/development/agents/<agent-name>.md and include an exclusive_authority block with note, rationale, and enforcement fields. Finally, run *pre-push to validate the configuration.

What fields are required in a story YAML file?

According to the constitutional gate implementation in /.aios-core/development/tasks/dev-develop-story.md, a valid story file at docs/stories/{id}/story.yaml must include: id (string), title (string), status (must not be "Draft"), acceptance_criteria (list), and tasks (list). Missing any of these fields results in a BLOCK status from the gate.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}