# NuQloud Scrum

NuQloud Scrum turns selected Talk channels into Scrum projects.

Canonical model:

| Talk | Scrum |
|---|---|
| Channel/conversation | Project |
| Thread/reply chain | Task |
| Thread replies | Task activity now; Deck card comments in the Deck mirror phase |

## Current v1 Flow

| Talk action | NuQloud Scrum result |
|---|---|
| Enable Scrum for a Talk channel | Creates a project workspace under the automation account's Files |
| Reply to a Talk message | Creates or updates a task |
| Continue replying in that reply chain | Appends task activity |
| Share a file in the conversation | Copies the file into project `Files/` when Talk exposes a file id |
| Share a file in a task reply chain | Copies the file into task `Files/` when Talk exposes a file id |
| Reply with `/doing`, `/done`, `/blocked`, or `/todo` | Updates the task status when bot commands are enabled |

Talk remains the primary workspace. Files and Deck are mirrors.

## Setup

1. Enable the app:

   ```bash
   sudo docker compose -f docker-compose.devprod.yml --env-file .env.devprod exec -T --user www-data app php occ app:enable nuqloud_scrum
   ```

2. Open Nextcloud as an admin.

3. Go to **Administration settings > NuQloud Scrum**.

4. Enable **NuQloud Scrum automation**.

5. Choose an **Automation account source**:

   | Source | Use when |
   |---|---|
   | Manual app password | You want a dedicated Talk automation account and app password |
   | Nextcloud admin env account | You want to reuse `NEXTCLOUD_ADMIN_USER` / `NEXTCLOUD_ADMIN_PASSWORD` |
   | Nextcloud service env account | You want to reuse `NEXTCLOUD_SERVICE_USER` / `NEXTCLOUD_SERVICE_PASSWORD` |

6. Set **Workspace filter** to **Selected conversations**.

7. Save settings.

8. Click **Sync workspaces now**.

9. In **Conversation Scrum**, click **Enable Scrum** on one Talk conversation.

10. Click **Sync messages now** after creating Talk replies in that conversation.

11. Click **View tasks** on that conversation to review synced tasks and statuses.

You can also open the Talk channel settings modal and use the **NuQloud Scrum** switch there. The switch is visible inside Talk and requires the current user to have Talk moderator access for that channel.

## How To Use

1. In Talk, create or choose a conversation.
2. Enable Scrum for that conversation in the NuQloud Scrum admin settings.
3. Post a message that should become a task.
4. Reply to that message.
5. Run **Sync messages now**, or wait for the background job.
6. In NuQloud Scrum admin settings, click **View tasks** for the conversation.
7. To update status, reply in the task thread with one of:

   ```text
   /todo
   /doing
   /done
   /blocked
   ```

8. Run **Sync messages now** again.

9. Open Files as the automation account.

10. Review the generated workspace:

   ```text
   NuQloud-Scrum/
     Conversation Name/
       _workspace.md
       _manifest.json
       Files/
       Tasks/
         123-task-title/
           _task.md
           _activity.jsonl
           _summary.md
           Files/
           Decisions/
       Decisions/
       Summaries/
   ```

## Automation Account Notes

- The automation account must be able to see the Talk conversations that Scrum should sync.
- The automation account owns the generated `NuQloud-Scrum` folder tree.
- In `Copy files` mode, file attachments are copied when the Talk payload exposes a resolvable Nextcloud file id.
- In `Store links only` mode, Scrum writes `.json` reference files instead of copying the attachment contents.
- If the source file cannot be resolved, Scrum writes a `.json` reference file instead and records the mirror state as `linked`.
- Env-sourced credentials are resolved server-side only and are not sent to the browser.
- If using the service env account, make sure the service user exists and can access the target Talk conversations.

## DevCloud Verification

```bash
sudo docker compose -f docker-compose.devprod.yml --env-file .env.devprod exec -T --user www-data app php occ app:list | grep nuqloud_scrum

sudo docker compose -f docker-compose.devprod.yml --env-file .env.devprod exec -T --user www-data app sh -lc 'for f in custom_apps/nuqloud_scrum/lib/Service/ConfigService.php custom_apps/nuqloud_scrum/lib/Service/TalkApiClient.php custom_apps/nuqloud_scrum/lib/Service/FolderMirrorService.php custom_apps/nuqloud_scrum/lib/Service/WorkspaceService.php custom_apps/nuqloud_scrum/lib/Controller/WorkspaceController.php custom_apps/nuqloud_scrum/lib/Settings/AdminSettings.php; do php -l "$f" || exit 1; done'
```

## Current Limits

- Status commands only run when **Enable bot-style task commands** is enabled.
- The Talk-native channel settings switch is implemented for project opt-in.
- Deck board/card mirroring is scaffolded but not yet implemented.
- Thread replies do not create Deck card comments until the Deck mirror phase is implemented.
- Existing workspaces created before the root rename may still have an old `NuQloud Scrum` folder until the project is re-synced.
- Summaries are scaffolded but not yet generated.
- Existing workspaces created before the `Tasks/` folder rename may still have an old `Threads/` folder.